Wiki-based Software Documentation

Ademar Aguiar, Gabriel David

FEUP and INESC Porto, University of Porto, Portugal

---

Tuesday, October 18, 2005, 1:30-5:00 pm, in the Esquire

A space to share your opinions and ideas about using wikis for documenting software.

Ademar Aguiar

---

Contents

• Introduction
• Goals
• Main theme
• How to Participate?
• Workshop preparation
• Workshop activities and format
• Agenda
• Post-workshop activities
• Organizers
• Workshop notes

Introduction

Wikis proved to be very appealing collaborative tools to present and edit web-based information, using a very simple markup language, a powerful dynamic-linking mechanism, and support to adaptive web pages.

This workshop aims at bringing together researchers, practitioners and tool developers interested in researching and exploring wikis as collaborative tools to support software development, in concrete for cost-effective software documentation.

Goals

The main goals of the workshop are the following:

• to identify key obstacles, opportunities, and challenges to wiki-based software documentation
• to plan the writing of a review/survey article, or a monograph, on the topic
• to envision an ideal wiki for software documentation in order to plan developing one
• and to build possible collaborations for future research and development.

Main theme

It is commonly accepted that good documentation benefits every software development project but its production and maintenance often consume a lot of development effort, especially when not done with appropriate tools and methods.

Programming and documenting is hard?

In addition to the highly demanding activities of programming, developers are often forced to contribute to several kinds of documentation (user documentation, architecture and design documentation, and internal documentation) in order to preserve and communicate the understanding they have about the software system under development.

The inadequacy of documentation techniques and tools ends up introducing difficulties:

• on the overall development process
• on the continual review and modification of documents throughout their life cycle
• and on preserving the consistency between the different kinds of artifacts involved (documents, source code and models),

issues that often compromise the programming productivity and/or the documentation quality.

Because to document is hard, and developers don?t see short term benefits on it, they often simply focus on programming, unless mandated, thus letting documentation almost neglected.

Wikis are very appealing documenting tools

Wikis proved to be very appealing collaboration tools to present and edit web-based information, providing a very simple markup language, a simple but powerful dynamic-linking mechanism based on lexical conventions, and its ability to support the notion of adaptive web pages.

Wiki documents are:

• open
• can be evolved incrementally and organically
• are easy to edit and organize
• promote convergence of contents and consistency of terms,
• are tolerant,
• and are easily observable by other users.

Due to their qualities and attractiveness, wikis are now widely spread on the web, especially in the software community, run on many different platforms, and are being used to serve different kinds of contents and documents of different knowledge domains.

Strengths and weaknesses of wikis for documenting software

As said before, this workshop focuses on the usage of wikis as tools for collaboratively editing software documentation.

There are many wiki sites being used to cooperatively develop software documentation, such as (Workshop2WikiExamples):

• drafts of designs and implementations
• design discussions,
• requirements gathering
• (please add here more kinds of document...)

However, there are still several open issues that would benefit from further research and development in order to leverage wikis to a wider and more effective usage as a tool for software development.

In fact, despite the richness and variety of the wikis available, only a few incorporate features specific to support software documentation:

• bug tracking
• tests
• language-specific source code formatting
• simple models
• dynamic-linking to source code repositories, such as version-control systems
• integration in open development environments
• (please add here more features...)

Although its current limitations for satisfying all the specific requirements of documenting software, wikis are already very helpful on supporting the collaborative edition and maintenance of software documentation, but much more can be probably done with a wiki in order to make them an unavoidable tool in software development.

In this workshop we will try to explore, discover, and understand the present limits of wikis to support software documentation, and to gather new ideas and challenges possibly to be addressed in future research and development on wiki technology.

How to Participate?

We?re interested in exploring wikis as a tool to support cost-effective software documentation.

We are also interested in a lively debate.

So, if you want to learn more about this topic or to share your research work, experience and ideas related with using wikis as a supporting tool to document software, you must participate.

In respect to software documentation, we think that wikis are good for:

• gathering, relating, developing, maintaining, and presenting software documents (requirements, design models, programs, tests, bug reports, etc),
• combining multiple kinds of contents (source code, models, structured text, free text, etc.), manually or automatically produced with software engineering tools.

Examples of relevant topics include, but are not limited to:

• report of experiences using wikis to support software documentation
• key features of wikis for software development
• specific markup languages for software documentation contents
• integration of wikis with software engineering tools (IDE?s, test tools, Q&A tools, version-control systems, etc.)
• integration of wikis with project management tools (communication tools, workflow systems, etc.)
• semantic preservation mechanisms between source code, models, and wiki-based documents
• wikis as a front-end for content management systems for software documentation
• (please add here your favorite topics)

Add a short biography (1 paragraph is ok) to let us all know a little more about you.

Share also your ideas, expectations or experiences responding to this call for participation in Workshop2Contributions! (see how below)

Workshop preparation

No special preparation is required to attend the workshop, but we would like to invite the attendees to contribute to the workshop by sharing their experiences, ideas, and expectations related with using wikis as a tool for documenting software in a cost-effective way.

This wiki of WikiSym is available for pre-, during, and post-workshop use.

A login and password are required to edit the wiki, but if you don?t have an account you can register or use the account provided by the workshop to log in as a Workshop2Participant and share your contribution in Workshop2Contributions. If you still need to know the user and password, please send an email to ademar.aguiar at fe.up.pt.

Workshop activities and format

This will be a 3 hours workshop on Tuesday, October 18, 2005, 1:30-5:00 pm, in the Esquire.

There will be perhaps 1 or 2 small formal presentations: an introductory one, to define the context, goals and expected results of the workshop, and a more visionary one to promote discussion and to push the limits of wikis as a documentation tool for software development environments.

As the goal is to explore, discover and understand the strengths and weaknesses of wikis for software documentation, we plan to do this by brainstorming sessions. We will probably set up a wiki during the workshop to take notes and for additional interactivity.

The workshop will be formatted according to the number of participants, but it will include a small introduction, a summary of the contributions and ideas gathered before the workshop, and organized discussions in workgroups about the theme of the workshop to draw possible future collaborations and research and development agendas.

Agenda

Here is an initial agenda:

• 1:30?2:0pm: Welcome. Summary of goals, contributions, and present state of the art and practice on wiki-based software documentation.
• 2:00?3:00pm: Exercises and discussion. (Notes)
• 3:00?3:30pm: Break (optional :-))
• 3:30?3:40pm: "The ideal wiki for software documentation", a visionary talk.
• 3:40-4:40pm: Exercises and discussion.
• 4:40?5:00pm: Consolidation and closing.

Post-workshop activities

The wiki (this or another one) will be kept alive after the workshop in hopes of continuing the discussion and collaboration. We hope to write a review or survey paper on the topic after the workshop in collaboration with the participants interested on co-authoring it.

Organizers

Ademar Aguiar teaches at Faculty of Engineering of University of Porto (FEUP) and does Research & Development at INESC Porto. He has specialized in the area of software engineering, mainly framework technology, design patterns, agile processes, and software documentation. Currently, his main line of research is on the development of a pragmatic approach to document object-oriented frameworks, which comprises a documentation model, an agile documentation process, and a set of collaborative documentation tools and utilities based on the WikiWikiWeb concept and XML technologies.

Gabriel David teaches at Faculty of Engineering of University of Porto (FEUP) and does Research & Development at INESC Porto. He has specialized in the area of large information systems, mainly business modeling, database systems, and university information systems, topics about which he has authored several research papers.

Participants

Ademar Aguiar

Costin

DJ is a software developer at Microsoft. Works in a group of 100+ developers that are contributing to wiki software documentation.

Uri Dekel is a PhD student at Carnegie Mellon University. Interested in using Wikis to support capture and documentation of the initial and informal software design during design meetings.

Angel Palazon

Tim

Frank

Matthias Jugel