New OpenNMS docs: Where to find them, why they’re better, and how to contribute

Originally posted to the OpenNMS blog by Bonnie Robinson, our resident documentation expert at OpenNMS.

If you look at the OpenNMS documentation, you’ll notice a change. Yes, it has a more polished appearance thanks to our new corporate branding, but it also has improved content and functionality as a result of our recent migration from AsciiDoctor to Antora for building the documentation.

Migrating the documentation was a huge undertaking (we’ll discuss the experience and challenges in a future blog), which required a new repository structure, syntax updates to almost every file, changes to our build environment, and a lot of tweaks along the way.

All the docs in one place, search functionality

We’ve consolidated all the product documentation in one place at a new URL: docs.opennms.com. From here you can access the current version (and some older ones) of the documentation for all OpenNMS components: Horizon, Meridian, Helm, Alec, PRIS, and OpenNMS.js. The documentation also contains top-level menu links to other great sources of information about the project: training videos, community discussion forums, archived documentation, and OpenNMS support.

Built-in search functionality lets you search all the documentation to easily find the answers you need. We have restructured some of the content, most notably in the Horizon/Meridian documentation:

• Release notes are now included within the core documentation
• Updated installation guide content now under “Deployment” menu
• Administration Guide now under “Operation”
• New “Reference” section with glossary and miscellaneous configuration topics

How to contribute

With the migration complete, our next steps are to improve and update the documentation. We want to remove out-of-date content and update anything that is incorrect or unclear. We want to add documentation for project features that don’t have any. Anyone can write documentation for the project, and we welcome any kind of contribution. (And if you are obsessed with documentation, please consider joining Write the Docs, our Mattermost channel devoted to all things documentation.)

Note that there are different ways to contribute documentation, each suitable for different use cases:

• Publish tutorials and how to articles in our knowledge base. For example, you want to describe how to use the Net-SNMP agent and the OpenNMS SNMP monitor to solve a special use case with OpenNMS. This is a great way to help other OpenNMS users who might have similar questions.
• Contribute formal technical documentation related to the source code on GitHub.
• Fix “quickwin-docs” Jira tickets in our documentation backlog. These are issues that should not take much time to address.

Technical documentation tips

File format for documentation is AsciiDoc, with the .adoc extension. For information on syntax, see Antora’s AsciiDoc Primer or look at how the existing .adoc files work.

Technical documentation should be accurate and concise. A good way to structure your contribution is as follows:

• Descriptive heading for new topics (for example, “Create a Minion” or “SnmpCollector”)
• Brief description of what you are documenting. If this is a new feature, include why it is important to users (for example, “This feature lets users validate and tune their business service hierarchies until they achieve the desired status propagation.”)
• Steps to complete the procedure, or technical content such as parameters, configuration, and examples

Minimize the use of screenshots. Include them only to illustrate a concept that may be difficult to understand or something that is not easy to locate in the UI.

Where do I contribute technical documentation?

Log in to GitHub and locate the repository for the OpenNMS component for which you want to contribute documentation (for example, opennms, opennms-helm). Navigate to the /docs directory. Within this directory, you will find the /modules directory, that contains all the technical documentation associated with the source code in that repository. The /modules directory may have more nested directories to create a hierarchy for the content (component, subcomponents).

You will find .adoc files in the /pages directory or one of the subdirectories within the /pages directory. Images go in the /assets/images directory. The following is an example of the core OpenNMS docs repository:

For more information on how to contribute to OpenNMS documentation, including formatting conventions, tips and tricks, and cheat sheets, see Develop Documentation. (Note that the introduction to the Develop Documentation topic contains outdated information. We will update it with the content from this blog for the next release.)

Happy writing and thank you for contributing to OpenNMS documentation!