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 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!