Ademar Aguiar

Beyond that, I will try to learn the more as possible from this event and the other participants.

Please contact me if you have any question, suggestion, feedback, or anything else about this paper and workshop at WikiSym'2005!

Ademar Aguiar

ademar.aguiar at fe.up.pt

CategoryHomePage

Seb's notes: (please edit):

Software development requires informal and personal communication, which usually works best, but sooner or later you need to produce documentation in order to preserve and share. After knowing and learning, you need to formalize information.

Good documentation is good but has a cost. We need to decide which is the right dose of documentation that guarantees the success.

Documentation is hard, costly and tiresome. You need to accomodate different purposes, audiences, kinds of reuse, documents, notations.

We have internal documentation, like JavaDoc, and higher-level external documentation that captures the components and connectors of an architecture. There is no place in the code to write this.

Here are some sample documents from JUnit. If you go to source code you'll see that they aren't consistent, though it doesn't matter here because the architecture is the same.

Here's an example of semantic inconsistency between source code and documentation.

The idea in Knuth's literate programming is to merge documents and code in a single file, but it is not very common. The programmer writes a literate document, with doc chunks and code chunks. You don't recognize the resulting code. There are serious integration difficulties with mainstream dev environments.

The single source approach (Javadoc, Doxygen) restricts documentation to follow the code's structure. In the case of a JUnit tour it's not appropriate.

The multiple source approach is the most traditional approach, but it results in inconsistencies as soon as one element is changed, which pushes developers to write the doc last so they don't need to update it.

Developers like to write in wikis. Wikis are simply great as documentation tools

AlainDesilets: I've started using wikis to document code, and I like it but can't quite pin down why that is.

Ademar: It's cool. Everyone sees what you've done. Immediate feedback is good.

Lion: Also you have issues that cut across.

Ademar: Students too, they love to use wikis to document. In a few weeks they produce hundreds of pages.

Delaying documentation over and over until the last moment is too late. You want to document immediately. If you've decided on a design, right now is the time to document it.

We didn't find a wiki that supports this, so we built one such system: XSDoc.

XSDoc Wiki extends a typical wiki engine with dynamic linking and inlining of source code, UML diagrams, instantiation and validation of XML documents, and document templates.

One thing is that you need to buy is a big screen.