Pattern: Documentation Roadmap

To completely satisfy all audiences and requirements, the documentation of a framework typically includes a lot of information, organized in different types of documents (framework overviews, examples of applications, cookbooks and recipes, design patterns, and reference manuals), that provides multiple views (static, dynamic, external, internal) at different levels of abstraction (architecture, design, implementation).

The complex web of documents and contents provided with a framework must be organized and presented in a simple manner to the different audiences, so that the readers don’t become overwhelmed or lost when using the documentation. In other words, the overall documentation must be easy to use by all kinds of readers, so that each individual reader can quickly acquire the strict degree of understanding she needs to accomplish her particular engineering task (reuse, maintenance or evolution).

How to help readers on quickly finding in the overall documentation their way to the information they need?

Different audiences. Readers of different audiences have different needs and interests that must be addressed by the documentation.

Different kinds of reuse. A framework can be reused in different ways, each requiring different levels of knowledge about the structure and behaviour of the framework, and therefore pose different demands on the documentation.

Easy-to-use. Despite its inherent potential complexity, the documentation must result easy-to-use.

Start by providing a roadmap for the overall documentation, one that reveals its organization, how the pieces of information fit together, and that elucidates readers of different audiences about the main entry points and the paths in the documentation that may drive them quickly to the information they are looking for, especially at their first contact.

The roadmap would help both when navigating top-down, from a main entry point of the documentation to concrete topics and subtopics, and when navigating bottom-up from a small piece of information to a bigger one to try to identify it as part of a whole, still unknown in a first contact.

To be effective, a documentation roadmap for a framework should be written in a task-oriented manner and to include the following aids:

• topics organized by audience, kind of task, and order of use, to help readers of different audiences quickly retrieval of the information they need to accomplish the tasks they have in mind;
• emphasis of the main entry points and subordination of the secondary ones, to improve visual effectiveness;
• overview of topics conveying how subtopics are related, to support non- linear readings;
• transitions and links to topics, and from them to the roadmap again, to improve the overall navigability around the roadmap.

Although all the above mentioned aids are important to include, in fact, the optimal level of importance assigned to each one depends on several factors: the framework being documented, which audiences are you willing to address in the overall documentation, which kinds of reuse to support explicitly in the documentation, and which tasks to emphasize and subordinate.

Independently of how these factors are balanced, the roadmap should be easy to use, easy to understand, well-organized, and visually effective, a set of quality characteristics that suggest not to include everything in the roadmap, but only the entry points and topics more relevant for the most important tasks of the target audiences.

JUnit. The JUnit framework provides a very simple documentation roadmap, where the audiences, kinds of reuse and tasks are implicitly mentioned in the names of the entry points in the documentation and their respective descriptions (Figure below).

The audiences addressed can be implicitly identified as the following:

• first-time users,which will probably be attracted by the “JUnit Cookbook” entry;
• selectors and common users, by the “Test Infected - Programmers Love Writing Tests” entry;
• and framework developers, by the “JUnit - A cooks tour” entry.

The kinds of reuse that are clearly expressed in this roadmap are:

• instantiating, by the “JUnit Cookbook” entry;
• selecting and instantiating, by the “Test Infected - Programmers Love Writing Tests” entry;
• and mining, by the “JUnit - A cooks tour” entry.

Finally, the tasks mentioned are simply how to implement tests.

This roadmap reflects the simplicity of the JUnit’s framework itself, the intent of the writers on making the documentation simple and short, by documenting the main usage task of JUnit: to write tests.

Swing. The Sun’s JFC/Swing framework is a popular example of a large framework for which exists a lot of documentation.

In part due to its large dimension and vast diversity of possible tasks when reusing Swing, be it black-box or white-box reuse, the roadmap is split along several documents, according to the kind of audience and reuse tasks.

The next figure presents “The Swing Connection - Index by Content”, which is the document of Swing that mostly resembles a framework documentation roadmap.

.NET. The Microsoft’s .NET framework is another popular example of a very large framework for which also exists a lot of documentation.

For this framework there exists a documentation roadmap that clearly addresses different audiences and different kinds of reuse, from where the reader is driven to other documents more specific to the kind of reuse selected with more detailed about the tasks possible with the framework.

The following figure presents the “Getting Started” document, which is intended to first-time (re)users, a secondary document accessible from the right-hand side menu that contains the main entry points to the documentation, organized by kind of audience.