Gardening Documentations

Abstract

This project can be filed under “H” for “Gardening”.
We changed the way of documenting the software OpenNMS to a different workflow.
The documentation is treated as code, lives in the same code repository and is released and versioned with OpenNMS.
As we plant the seeds with making those changes a few years ago there is now time for “Gardening” cause things grew out in a few places.

This proposal is to improve the usability of our documentation in the following:

  • Refactoring: Rearrange topics and use a Reference section to collect things like “List of all documented Monitors, Collectors, Notification Commands, etc.” and remove them from the sections where things are explained.
  • Merge the User and Administrator guide: There are several reasons for this. The terms User and Administrator are overloaded and we have unnecessarily duplicated content we have to maintain. Also, the search is harder and is impractical cause the topics are too close.
  • Evaluate if we use state of the art technology. Meanwhile, there are several documentation frameworks which can be used to improve the usability. Ronny evaluated AsciiBinder which is used in the Helm documentation and is working on the Antora project to figure out if this is suitable for our project. Antora is a relative young project and built from the maintainer of AsciiDoctor.

During DevJam I would like to propose a project focusing on the topic “Refactoring” and if it’s enough time left on the Merge User and Administration Guide.

Folks

Communication Channel

Notes

Technology

  • AsciiDoc
  • Git and GitHub

OpenNMS Components

  • Documentation

Talk