27. 12. 2018 Charles Callaway NetEye, Unified Monitoring

Research & Development – A New User Guide Process (Part 4)

Software grows. So do software teams. To avoid getting slow and rusty over time, teams need to constantly assess their progress, improve where they can, and make necessary changes when warranted.

The NetEye R&D team is no exception. Back when NetEye was smaller, we wrote documentation when time allowed, typically after new features had already been implemented. The result was a user guide that became more disjointed over time, requiring heroic efforts to bring the code base and guide back into alignment, often the week before release. But you shouldn’t need to repeatedly undertake heroic efforts to keep code and documentation aligned with each other.

The Agile method is a series of processes (initially intended for developing code) that can be adopted to make this continuous renewal become more automatic over time. The Agile method isn’t fixed in stone, however. Every so often, it becomes clear that new techniques can be included that will further improve the overall process of software delivery.

One of these recent additions is the idea of writing documentation in the same way that you write code. One of the premier agents for this change is the Write the Docs movement. While the organization serves as a professional community for technical writers, it is also a principal proponent of using existing Agile methods to improve the documentation process.

The principal ideas of the Agile framework might be condensed to (1) incremental, iterative work, (2) frequent delivery in short time spans, (3) being prepared for and capable of adapting to necessary internal and external changes quickly, (4) using working software as the primary measure of progress, and (5) self-evaluation of the entire software development process at regular intervals.

So how then should writing a user guide be integrated into the standard software development process? We have taken the following approach:

The technical writer participates as a member of the development team, attending all Agile-based developer meetings such as the Stand Up, Backlog Refinement,
Poker Estimation, Kanban management, etc.
Documentation is written concurrently with the code. Sometimes prototype documentation is even created as soon as the product requirements are written, allowing developers to ensure the documentation is correct and complete while everything is still fresh in their minds.
Documentation must go through a testing phase just as code does. For instance, the technical writer follows all procedures added to the NetEye 4 user guide before the code is even reviewed in order to make sure they work.
Documentation must go through a review phase just as code does. Developers must read and explicitly accept the full documentation for their task before continuing.
Developers can be “blocked” by unwritten documentation. Software cannot be released until the full documentation is also ready.

The user guide should be trusted as the authoritative repository of knowledge about how a software product works. But how do you get to that point? With the procedure above and the logic of induction: if we start with correct and complete documentation, and every subsequent change to the code base is accompanied by correct and complete documentation, the user guide will never be in a state where it is not correct and complete.

We’ve been reworking our development processes to ensure that this is true for the NetEye 4 user guide. We hope you enjoy the results!