WikiWiki weaving heterogeneous software artifacts

ABSTRACT

Good documentation benefits every software development project, especially large ones, but it can be hard, costly, and tiresome to produce when not supported by appropriate tools and methods.The documentation of a software system uses different artifacts, namely source code, for low-level internal documentation, and specific-purpose models and documents, for higher-level external documentation (e.g. requirements documents, use-case specifications, design notebooks, and reference manuals). All these artifacts require continual review and modification throughout the life-cycle to preserve their consistency and value.Good software documents are often heterogeneous, i.e., they combine different kinds of contents (text, code, models, images) gathered from separate software artifacts, a combination usually difficult to maintain as the system evolves over time, considering that source code, models and documents are typically produced and maintained separately in multiple sources using different environments and editors.This paper presents a wiki that helps on quickly weaving different kinds of contents into a single heterogeneous document, whilst preserving its semantic consistency. The fundamental goal of this wiki (XSDoc Wiki) is to reduce the development-documentation gap by making documentation more convenient and attractive to developers. An example taken from the JUnit framework documentation helps to illustrate the features more relevant to do such weaving.

REFERENCES

• 1: A. Aguiar. A minimalist approach to framework documentation. PhD thesis, Faculdade de Engenharia da Universidade do Porto, September 2003.
• 2: A. Aguiar, G. David, and G. Badros. JavaML 2.0: enriching the markup language for Java source code. In Proceedings of XATA 2003, XML: Aplicaes e Tecnologias Associadas, February 2004. http://www.fe.up.pt/~aaguiar/javaml/.
• 3: A. Aguiar, G. David, and M. Padilha. XSDoc: an Extensible Wiki-based Infrastructure for Framework Documentation. In E. Pimentel, N. R. Brisaboa, and J. Gómez, editors, JISBD, pages 11--24, 2003.
• 4: Kenneth M. Anderson , Susanne A. Sherba , William V. Lepthien, Towards large-scale information integration, Proceedings of the 24th International Conference on Software Engineering, May 19-25, 2002, Orlando, Florida [doi>10.1145/581339.581403]
• 5: Greg J. Badros, JavaML: a markup language for Java source code, Computer Networks: The International Journal of Computer and Telecommunications Networking, v.33 n.1-6, p.159-177, June 2000
• 6: K. Beck and E. Gamma. Junit: A cook's tour, 2003. Available from http://www.junit.org.
• 7: Richard Bodner , Mark Chignell, Dynamic hypertext: querying and linking, ACM Computing Surveys (CSUR), v.31 n.4es, Dec. 1999 [doi>10.1145/345966.346002]
• 8: R. Bodner, M. Chignell, and J. Tam. Website authoring using dynamic hypertext. In Proceedings of Webnet'97, Toronto: Association for the Advancement of Computing in Education, pages 59--64, 1999.
• 9: A. B. Coates and Z. Rendon. xmLP a Literate Programming Tool for XML & Text, 2002. http://xmlp.sourceforge.net/.
• 10: Michael L. Collard , Jonathan I. Maletic , Andrian Marcus, Supporting document and data views of source code, Proceedings of the 2002 ACM symposium on Document engineering, November 08-09, 2002, McLean, Virginia, USA [doi>10.1145/585058.585066]
• 11: G. Cronin and B. Barnett. Very quick wiki homepage, 2003. Available from http://veryquickwiki.sourceforge.net/.
• 12: W. Cunningham. Portland pattern repository., 1999. Available from http://c2.com/cgi/wiki.
• 13: Eclipse. Eclipse, an open and extensible integrated development environment, 2003. Available from http://www.eclipse.org.
• 14: O. M. Group. XML Metadata Interchange (XMI), 2005. Available from http://www.omg.org/.
• 15: S. C. Gupta, T. Nguyen, and E. V. Munson. The software concordance: A user interface for advanced software documents. In Proceedings of 6th IASTED International Conference on Software Engineering and Applications, MIT, Cambridge, MA, USA, November 2002.
• 16: Jochen Hartmann , Shihong Huang , Scott Tilley, Documenting software systems with views II: an integrated approach based on XML, Proceedings of the 19th annual international conference on Computer documentation, October 21-24, 2001, Sante Fe, New Mexico, USA [doi>10.1145/501516.501571]
• 17: M. L. Jugel and S. J. Schmidt. SnipSnap Wiki homepage, 2003. Available from http://www.snipsnap.org/.
• 18: M. Knasmüller. Reverse Literate Programming. In Proceedings of the Software Quality Conference, Dundee, 1996.
• 19: Donald E. Knuth, Literate programming, The Computer Journal, v.27 n.2, p.97-111, May 1984 [doi>10.1093/comjnl/27.2.97]
• 20: Douglas Kramer, API documentation from source code comments: a case study of Javadoc, Proceedings of the 17th annual international conference on Computer documentation, p.147-153, September 12-14, 1999, New Orleans, Louisiana, United States [doi>10.1145/318372.318577]
• 21: E. Mamas , K. Kontogiannis, Towards Portable Source Code Representations Using XML, Proceedings of the Seventh Working Conference on Reverse Engineering (WCRE'00), p.172, November 23-25, 2000
• 22: K. Nørmark. An elucidative programming environment for Scheme. In Proceedings of NWPER'2000 - Nordic Workshop on Programming Environment Research, pages 109--126, May 2000.
• 23: Kurt Nørmark , Max Andersen , Claus Christensen , Vathanan Kumar , Søren Staun-Pedersen , Kristian Sørensen, Elucidative programming in Java, Proceedings of IEEE professional communication society international professional communication conference and Proceedings of the 18th annual ACM international conference on Computer documentation: technology & teamwork, September 24-27, 2000, Cambridge, Massachusetts
• 24: H. P. Report. Towards modern literate programming.
• 25: Johannes Sametinger , Gustav Pomberger, A hypertext system for literate C++ programming, Journal of Object-Oriented Programming, v.4 n.9, p.24-29, Jan. 1992
• 26: Sun Microsystems. Javadoc Tool Home Page, 2003. http://java.sun.com/j2se/javadoc/.
• 27: P. Thoeny. Twiki homepage, 1998. Available from http://www.twiki.org/.
• 28: D. van Heesch. Doxygen --- a documentation system for C++, Java and other languages, 2002. Available from http://www.doxygen.org.
• 29: B. Vibber. Mediawiki homepage, 2001. Available from http://www.mediawiki.org/.
• 30: Fabio Vitali , Michael Bieber, Hypermedia on the Web: what will it take?, ACM Computing Surveys (CSUR), v.31 n.4es, Dec. 1999 [doi>10.1145/345966.346030]
• 31: N. Walsh. Literate Programming in XML, Oct. 2002. http://nwalsh.com/docs/articles/xml2002/.
• 32: C. Walton. EclipseWiki homepage, 2003. Available from http://eclipsewiki.sourceforge.net/.
• 33: World Wide Web Consortium. XSL Transformations (XSLT) Version 1.0, November 1999. Available from http://www.w3.org/TR/xslt.
• 34: World Wide Web Consortium. XQuery 1.0 and XPath 2.0 Data Model, November 2002. Available from http://www.w3.org/TR/2002/WD-query-datamodel-20021115.

INDEX TERMS

Primary Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.6 Programming Environments

Additional Classification:
  I. Computing Methodologies
  I.7 DOCUMENT AND TEXT PROCESSING
      I.7.2 Document Preparation
          Subjects: Markup languages; Hypertext/hypermedia

Keywords:
Wiki-based software documentation, software documentation, web-based documentation, wiki