Agile documentation keeps software instructions current with frequent updates. It focuses on user needs by providing clear explanations, new feature breakdowns, and migration guides. Easy navigation, search, and collaboration tools ensure users can find what they need quickly.
The Agile Manifesto emphasizes, "Working software over comprehensive documentation," but that does not imply that documentation is not important, since without some documentation the software features and usability may not be known. Moreover, regulated industries require documentation. Software documentation, like the software itself, needs to be updated periodically. This article explores how to make documentation development agile to keep it in sync with agile software development.
Supported Platforms
Let’s say a user is familiar with a particular software, but they need to find out whether the software can be run with certain operating system platforms and other associated software. For a user to be able to start using a new software, a list of supported platforms should be provided at the outset. The supported platforms or systems should be grouped into categories, for example, Oracle JDeveloper and ADF 12c (12.2.1) Supported Systems.
New Features
First and foremost, each new software version (major or minor) should be accompanied by a new features documentation, such as What Is New in [Software] Version [n.nn]. The new features documentation includes a detailed description of each new feature, illustrated with examples. It should also include a discussion on:
- What is the benefit of the new feature,
- Who should use the new feature,
- When should the new feature be used, and
- Any dependencies the new feature requires to be pre-installed
Diagrams should illustrate any concepts and procedures involved. The new features could be grouped into top-level features, minor enhancements, configuration-related changes (such as new settings and variables), and any internal new features that a user does not directly use but is affected by.
The new features should also include features that are deprecated. An alternative solution should be recommended in lieu of the deprecated features. Any features that are removed should also be discussed, or at least listed.
Group Documentation by Version
To keep documentation agile, it should be grouped by version so that a user does not have to sift for information from an ever accumulating documentation heap. A drop-down list can be provided to choose documentation for a specific version. An example drop-down is shown in MySQL Server documentation.
Migration Guide
A migration guide should be provided for a user to be able to migrate from one version to another—usually from an earlier version to a later version. A migration matrix may be included in table format for easy reference to supported/unsupported migration paths. An example migration matrix is shown for JDeveloper migration.
The migration guide should discuss not only the procedure to migrate, but should also provide recommendations on:
- When to use a specific version
- Any requirements for compatible software
- Any tools that facilitate migration
Code Examples
Develop new code examples for new features. Some developers find it easier to directly adapt existing code examples for their use case. Code examples should be included for each of the supported programming languages.
The existing code examples should be retested with each new software version as software changes may require changes to code examples. Even if no software changes affect code examples, the code should be retested with the new software to ensure that no new software bugs have been introduced.
A user should be able to copy code to the clipboard with a single click on a linked icon, usually in the top-right corner of a code example.
Automated scripts to test code examples can be used, as a user testing each code example could be time-consuming.
Agile Navigation
Even if a documentation stores all the information about a software, if the documentation is not easily navigable the information may not be of much use.
Add navigation in the margin and at the page’s top and bottom. The navigation hierarchy should not exceed 2-3 levels as a higher level hierarchy requires adjustments to margin/page width. The navigation links should be color-coded to be able to distinguish between a selected and an unselected link.
Text on a page should be cross-linked to other pages whenever a reference is made to another topic covered in another section on a separate page. A previous/next link each should be included on a page to navigate to next/previous pages rather than relying on the browser’s navigation buttons. A navigation history could be provided, which could be placed in the right margin.
Search Feature
Documentation should be easily searchable for it to be agile. Documentation that stores all the information but is not easily discoverable is not of much use. A search engine could make use of one or more of the following approaches:
- Search algorithms
- Collaborative filtering
- Content-based filtering
Collaborative filtering and content-based filtering are a subset of recommender systems. Collaborative filtering makes use of a user’s past searches and may even include searches made by other users. Content-based filtering is based on the tags and characteristics of the data searched for and does not rely on past search history.
Use Cases
Agile documentation does not solely explain how to use the software and its features—it makes recommendations and suggestions about the use cases for the software and its specific features. Use cases usually include examples that an end user can adapt.
Usability and UX
Usability and UX (User eXperience) are relatively new as discrete fields and were bundled with web design earlier on. Usability of documentation refers to how easy it is to use it, which includes some of its aspects discussed earlier such as navigation, searchability, and grouping relevant information. UX is more of an overall experience a user has and may be derived from several user preferences such as font type, font size, font color, design of dialogs, drop-down lists, navigation bar, and message dialogs. The UX-related settings should be customizable.
Collaboration
An important agile principle is collaboration. Agile documentation development proactively collaborates between end users, software developers, and documentation developers. Scrum and Kanban are some common frameworks used for collaboration.
Conclusion
In summary, agile documentation:
- Provides all the relevant information including supported platforms, new features, and a migration guide
- Information is up-to-date and illustrated with code examples and diagrams
- Information is grouped and prioritized and includes use cases & recommendations
- Information is usable (Usability factor)
- Documentation takes into consideration a user’s experience (UX factor)
- Makes use of collaboration between stakeholders
