01. 12. 2019 Charles Callaway Documentation, NetEye

Squaring the User Guide Circle

The official Icinga 2 user guide is quite extensive, but it’s not always complete. That’s normal in today’s world of fast changing software where the focus is on delivering new capabilities quickly. Even here at NetEye most of the documentation we produce for our user guide is written when we add new modules and features, and is focused specifically on describing those new elements. But this approach doesn’t work if there are already gaps in the existing user guide.

There are a number of reasons why gaps in a user guide may arise:

The need for documentation was not addressed at the start of the project. For instance, a technical writer might not be hired until after a project is already well underway.
Writing documentation was not prioritized, and thus fell behind development and became incomplete.
Some topics were described too quickly, for instance only conceptually without any details or examples, or only as a reference guide, with lots of detail but no explanation.
Part of the guide was directed at a particular audience or perspective (e.g., using a command line or config files, but not the web interface).

It is important to make sure that the user guide that accompanies software is both as up-to-date as possible and is complete (i.e., without gaps). And so as part of each NetEye release, in addition to adding new documentation corresponding to new and updated functionalities, we also search the user guide for gaps in the existing documentation.

How do we find these gaps? Sometimes it becomes apparent when we check our existing documentation by reading what we write and testing it ourselves (known colloquially in the software industry as “eating your own dog food”). Or by trying out basic tasks given an empty NetEye system. We also solicit suggestions from others, such as our consultants and support staff, in order to identify what customers think is missing. In all these cases we will create documentation from scratch and add it to the user guide.

One such recent case is the documentation for User Authentication, which falls into category #4 above: in the user guide it was originally written from the perspective of the command line interface rather than for the web interface. The solution here was clear: rewrite the documentation from scratch, addressing both the conceptual background and instructions on how to use the system, while conforming to the latest NetEye standards. Having done that, we are pleased to report that if you’ve ever found yourself needing to add more users, user groups or authentication backends, you will soon find detailed instructions in the section *User Guide > Initial Configuration > User Authentication and Permissions*. This new user guide section will be included starting from NetEye 4.4, and backported to NetEye 4.3.

If you’ve ever come across a problem where the information you need can’t be found in the user guide, the solution is also clear: let our consultants and support staff know about it! That’s the best way to make sure we address it as quickly as possible.