08. 07. 2019 Charles Callaway Documentation, Unified Monitoring

“How To” Improve the User Guide

Every software suite needs documentation. But the more features we add to NetEye to meet customer needs, the larger the user guide becomes. Over time, it’s important to make sure that the guide continues to meet the needs of NetEye users despite this.

In particular, modern methodologies like Agile that we use in NetEye often focus on incremental improvements to the codebase, and expect newly written documentation to correspond tightly to those changes. So it’s easy to lose sight of the overall goal of having a user guide in the first place: making it easy to learn how to use the software to accomplish your goals.

That’s not to say that the Agile approach is unhelpful (or even hurtful) to good documentation. For instance, it ensures that what’s written is correct and complete. But “complete” is from the code writer’s perspective, not the user’s perspective. When you document many small steps one at a time, it’s easy to forget that most use cases for the software need to connect a larger number of those small steps together in order to achieve the user’s goal.

To combat the “myopic” tendency imposed by this approach, technical writers supplement the highly detailed technical explanations in the user guide with easily followable “How To” guides that show a user the individual steps necessary to accomplish a larger task. Even better is to base each How To on a real world use case for the software.

NetEye is no exception. Recently as part of our continuous updates to our Agile processes, we have begun to ensure that good How Tos are included in the user guide in a standard way. Each How To complements the new documentation and is paired with it in the guide, referencing it frequently.

And because it’s now completely integrated into our workflow, we will continue to create future How Tos for NetEye, improving the user guide in a positive way.