Documentation Strategy

From StatusNet

Contents 1 Framework 1.1 Capture 1.2 Organize 1.3 Translate 1.4 Output 1.5 Review 1.6 Revise 2 Audience and types of documents 2.1 Web-based promotional material 2.2 Developer dictionaries 2.3 API summaries 2.4 Task-centric consumer manuals 2.5 Third-party documentation

[edit] Framework

Usable documentation is information that is easy to maintain, up-to-date, tested and task-centric. It is available at the point of need and is written in a task-centric way that allows readers to glean the information they need to accomplish the task at hand. A successful framework includes a cycle of work:

Wherever possible, documentation has a single “canonical” source that is machine-readable and can be output to various formats (including those necessary for translation). The cycle updates this single canonical source which is used to populate multiple human-readable formats in multiple languages.

[edit] Capture

The first task to to determine everything that needs to be documented. The most efficient way of collecting this material is to brainstorm a list of every single thing that someone interacting with StatusNet will want to know. Prospects, end users, administrators and developers should be considered in the list of documentation “consumers.” The goal is not to write all of this information, but to capture the framework of information that must be presented to the user.

[edit] Organize

Once the topics are captured, the items should be sorted according to task, role and prerequisite knowledge. This gives the master plan for all future written work. It will show where automation is possible and where duplication may arise. This sorting must happen in a machine readable language, such as DocBook, DITA or Mallard. Non-XML languages are also available such as reST. To facilitate automation, the markup language chosen should work well with the other tools StatusNet has chosen. Topics without corresponding information will need to be written at this at this stage.

[edit] Translate

While at the machine-readable stage, all information should be pushed to a translation interface. At this point StatusNet is planning to use TranslateWiki for UI string translation. Brion Vibber is checking with TranslateWiki to see if they are capable of handling larger documents.

[edit] Output

Once translated, the content can be formatted and pushed to its appropriate place according to type of document and type of audience. This may include HTML, PDF and Wiki formats. At the output stage multiple transformation style sheets may be applied that will allow vendor branding of content. Output tools will depend the tools used to organize content; however, DocBook and Apache FOP are one of the more popular XML tool sets used for open source documentation projects.

[edit] Review

Documentation must be updated at least once per major release. Review should be crowdsourced to reduce the burden on the StatusNet team. Feedback mechanisms could include: comments (see php.net documentation), rating+review system, community editable Wiki. The review phase ensures documentation is useful and therefore more rewarding for the documentation consumers and contributors. It helps to keep information in the organizational framework and identifies problems with the framework. Pushing documentation to a Wiki provides the community with the greatest opportunity to give feedback on the documentation. Where possible all documentation should be tested to ensure instructions are clear, concise and correct. To ensure each release ships with completed documentation, the review platform maybe be closed toward the end of the release cycle to ensure revisions can be entered and translations can be completed.

[edit] Revise

In the final stage of each major release for documentation, feedback should be collated from each language and each vendor branch. The collation will depend on the review system used. Sensible review comments should result in a patch made to the canonical source for documentation. Where there is an excess of documentation, the revisions should be carefully reviewed to see if the UI can be simplified to decrease the amount of documentation required.

In the next documentation cycle: new information for new functionality must be captured, the information must be organized, translated and published to each of the output formats.

[edit] Audience and types of documents

Each major release of StatusNet will need to have a revision of its documentation. Starting for the 0.9 release, StatusNet should consider multiple types of readers and create automated processes for each of:

1. prospects
2. end users
3. administrators
4. developers

Within these types of readers there may be several unique audiences; however, the type of documentation will be contained within the same workflow. A combination of the following types of documents will be required:

1. Web-based promotional material for prospects. Includes includes to relevant consumer documentation. This will include sample implementation documents and case studies showing how to be imaginative with StatusNet.
2. Developer “dictionary” of functions to be scraped from the code (see php.net as an example).
3. API summary documents which cannot be pulled directly from the code base (see http://apiwiki.twitter.com/).
4. Task-centric, consumer manuals for end users, administrators and task-centric manuals for developers wishing to create plugins for StatusNet.

Each of these types of documents will need its own workflow. This list does not include internal documentation for StatusNet (hosted on the company Wiki), UI text in the StatusNet code base or inline help, which is also contained in the code base. Inline help can be adapted from the task-centric consumer manuals (or the task-centric consumer manuals can be created from the inline help).

[edit] Web-based promotional material

Selling the benefits of StatusNet to new consumers is anything but a series of tasks to be performed. The Web site will reference features available in StatusNet but address the benefits and “why” of StatusNet instead of the “how to.” Documents on the public-facing Web site may also include top-level architecture and “white papers” about StatusNet.

Web-based material should be promotional in nature. It may appeal to several different audiences including end users, and decision-makers looking to “buy” new technology. No HOWTO instructions should be included in the StatusNet “promotional” Web site. When it is relevant, portions of the Web site may be included in the machine-readable “canonical” source of documentation to enable translation.

[edit] Developer dictionaries

To be effective, good documentation needs to be part of the product development culture. The product owner must define the standards for documentation and insist they are adhered do. Documentation needs to be easy to update. It should reside as close as possible to the point of need for the consumer, and to the point of work for its writers. In other words: put the documentation for developers where they are writing code; and display the documentation where (and when) the reader needs it.

The easiest type of documentation to automate is the developer dictionary (or code reference). By insisting on useful documentation in the source code, it becomes nearly “trivial” to extra text that is useful to developers using tools such as phpdocumentor.

No new code should be added to the code base that is not documented. As soon as possible these code comments should be extracted and made available through a Web site. Where relevant, comments should be enabled and reviewed by developers once per release cycle. Patches should be welcomed by developers who wish to improve internal documentation.

[edit] API summaries

Unlike the developer dictionaries, API summaries do not have a one-to-one correlation to the functions in the code-base. These summaries should be automated where possible and include sample output from the code. Writing these documents at the “code” level, instead of a Web-based GUI will allow developers to switch tasks easily and update the API summaries. They should be pushed to a Web site where the community can participate in their upkeep through the review process described above.

[edit] Task-centric consumer manuals

Computer manuals typically describe features available in software and require the user to invent tasks when they might want to use these features. To be truly useful, documentation should the information that is required at the point of need—like the assembly instructions slipped into an IKEA box. The source for task-centric consumer manuals should be contained in a single, machine-readable location. Steps should be tagged according to role and prerequisite knowledge required to complete the tasks. To produce a “Developer” manual, all information in the source material should be filtered according to role and output in a linear fashion according to prerequisite knowledge. The full workflow for these manuals is described in the document framework section at the beginning of this document.

Although there are numerous markup languages, the ones with most powerful output tools are XML-based. DITA (Darwin Information Typing Architecture) structures information according to topics and its relationship to other topics. DocBook, traditionally used to describe software features and functionality, sorts information according to “chapters” in a book. Although both DITA and DocBook can be used to produce documents in the other's area of specialization, it is easier to use DocBook for “books” and DITA for “information typing.” DocBook has a longer history in the open source world; DITA is not as common in open source projects. Both DocBook and DITA require specialized knowledge in markup language and will limit the number of volunteers contributing to the documentation source.

Mallard, a relatively new topic-based markup language crated by the GNOME documentation team, is similar to DITA, but is optimized for digital help-systems and has a limited number of output formats. If linear, printed books are not a priority for StatusNet, consideration should be given to Mallard as it is easier to learn than DocBook, with the features of information typing present in DITA, and with a strong commitment to accessibility and translation for open source projects.

[edit] Third-party documentation

Ideally all third-party documentation will use the framework described above for each of: Web based promotional material (a “project page”); developer dictionaries and API summaries; and consumer manuals. Realistically projects may only be comfortable with the automated wiki pages that are provided by the “output” stage described in the framework section of this document. Support should be provided by StatusNet staff to help third-party plugins find documentation support from within the community.