One of the action items from the M1 Lessons Learned was to "Investigate ways to make the documentation available to developers in the builds and synchronized with the wiki"

There are two categories of documentation associated with Project Zero: concept documentation and API reference.

API Reference

API reference should be generated from the source code. This maintains tight integration and allows staging of changes with the corresponding code.

JavaDoc is the standard for Java APIs; seems we should stick with that for Java APIs. Zero developers should use the @zero doclet tag to indicate public APIs (@zero API) and SPIs (@zero SPI).

PHP doesn't have a clear standard (Charlie?), so this is a good opportunity for innovation. Charlie Surface has developed a means of generating/updating TWiki markup for PHP APIs, derived from the P8 SAPI Java source. The results include the expected index page and formatted detail pages, as well as automated insertion of example .php files.

At this point, we don't have many Groovy-specific APIs. (Even the method bindings have been called into question.) If Groovy-specific APIs emerge, then we should consider a generated format similar to that for PHP.

Follow-up

• Add a mechanism (doclet tag?) to insert examples into JavaDoc. Sometimes only a snippet of a class implementation is desired in the docs; consider a special comment delimiter to facilitate extraction.
• Include the example files in unit tests in order to reduce mistakes in the documentation.
• Add active comments to the documentation pages?
• Set styling on the Zero JavaDoc to match the Project Zero Web-site styling?
• Cleanup generated PHP API documentation
  • Modify TOC pages
    • Add all letter links to each page
    • Add the current letter in bold
    • Add brief function description next to name

For the PHP documentation we use the twiki plugin to search other pages and create an uptodate list of functions. Have a look at http://www.projectzero.org/wiki/bin/view/Documentation/PhpDevelopersGuideFunctions which uses the %SEARCH macro.

Concept documentation

Concept documentation is generally more verbose and randomly interconnected than API documentation. It's also not generally associated with any specific source code, so this form of documentation must be handled differently.

Our primary maintenance problems with concept documentation are:

• Difficulty staging updates before publishing
• Updating all the "right" places in reaction to concept/API changes

We talked about putting the raw TWiki markup in SVN under a documentation project as a way to solve problems with staging and synchronization, but that approach has challenges:

• Disjoint edit/view cycle. This could be eased by adding a TWiki previewer (TWiki markup plus site styling) to the Zero development environment.
• Disjoint page creation. Wikis make page creation easy. The documentation project would probably have source files arranged to match the URIs in the TWiki; "publish" would be a simple HTTP POST of the new content. Would we need to be able to create a new page from this process? Or should page creation become more of an administrative task performed on the TWiki directly?

We could also look at tighter integration into the TWiki implementation, but one begins to question why we'd continue with TWiki if it's only being used as a rendering/versioning engine. (TWiki might still have value for other aspects, such as meeting minutes, etc.)

For now, it seems best to continue with TWiki (rather than solve the above challenges). We could improve the concept documentation by leveraging the tested examples where source examples are used. This also helps to address updating the "right" places in reaction to API changes. But the ripple effect from concept changes must be managed manually.

Follow-up

• Include tested examples into concept documentation where source examples are used. TWiki plugin?
• Consider another platform for concept documentation? Another Wiki? Eclipse help? A custom, Zero-based Wiki container for rendering content and managing comments?