Bonnie Robinson, The OpenNMS Group
February 15, 2022
As an open-source company, The OpenNMS Group benefits from direct user feedback through community engagement channels (Mattermost, Discourse) and the ability for anyone to contribute to the documentation. If users have issues, they can contact us, create a Jira ticket, or update the documentation themselves.
Community Engagement Channels
We use Mattermost as our online chat service for internal and external communication. Public discussion channels include OpenNMS Development and OpenNMS Discussion, where users post questions, seek technical support, and communicate with developers about improvements and making contributions to the project. We monitor these channels for trends: the frequency of questions on related topics prompts a review of the documentation to determine if it needs updating. Sometimes users simply state that the information is not in the docs, or that it is insufficient. We note these and add them to our list of documentation tasks.
For the truly hardcore documentation-obsessed, we offer the Write the Docs channel where we discuss current and future docs work, both content and technical implementations.
Open-Source Access on GitHub
Each topic in our documentation has an “Edit this Page” link that takes users to the page source on GitHub. The user can make changes and create a pull request to have their changes added to the documentation. They must sign a contributor’s agreement and a member of the technical writing team or a subject matter expert reviews the pull request. Users can also log in to GitHub directly to make changes, following a similar contribution/approval process. This access not only helps keep the documentation accurate, but being able to contribute also gives our users a sense of ownership in the project.
OpenNMS Discourse
We host a community forum on Discourse where, like Mattermost, users ask questions and participate in discussions about the project. When we undertook a migration of our documentation build environment, we posted about it in Discourse and invited people to comment or contribute to the process.
Our Discourse forum also includes a community-generated knowledge base: a rich source of information beyond the official documentation. Our documentation includes links to many of these KB articles, and we migrate particularly useful KB articles into the official documentation.
Meeting with the Support Team
We hold monthly meetings with the team that provides support for the commercial version of OpenNMS to determine the most common issues customers contact them about. When we see a lot of support tickets for the same problem we check to see if updating the documentation will help. As heavy users of the documentation, members of the support team also contribute to its development, identifying errors and gaps, often updating it themselves.
Some Documentation fun at Hacktoberfest
Hacktoberfest is an annual, month-long event that encourages people to participate in the open-source community. Participants sign up to contribute changes to open-source projects and earn swag. In 2021, OpenNMS included its documentation as a qualifying project for people to contribute to. Doing so made users and non-users aware of our documentation and gave them an incentive to contribute to it. Those contributions go beyond user feedback, as they needed to be substantive (not simply fixing a typo), requiring someone to identify deficiencies in the docs that they could address.
Few would argue that good documentation requires experienced, professional technical communicators on staff. But an open-source environment demonstrates the huge benefit that users bring when they directly contribute to and influence documentation creation.
Bonnie Robinson is lead communications professional at The OpenNMS Group, with over 25 years of experience as a technical writer and editor. She oversees the production of the group’s technical documentation and marketing content.