Competitive Analysis on NMS Documentation

[iirisgao]

Competitive Analysis on NMS Documentation

Related issue: #9848

One of our goals of the open source Network Management System (NMS) is to enable all users to find the information they need from the documentation. Improving the quality of documentation is one of the priorities towards the graduation of Magma. To find out the gaps and opportunities, we did a competitive analysis on the product documentation of 4 open source NMS products: Zabbix, Ubiquiti (UISP), OpenNMS, and LibreNMS. Here’s a summary of the high level findings.

Developers Contributing to the Documentation

Some NMS allow the community developers to create and publish documentation to describe the features they added. They also provide guidance and instructions on how to write the docs.

LibreNMS guidelines for creating documentation

OpenNMS rules for developing documentation

Change Log, Release Notes, and Version History

All four NMS publish release notes to inform the user of the new features, changes, and product updates of new releases. They keep a record of past versions since the user may not always be on the latest version.

Zabbix keeps the documentation for difference versions

The What's new section on Zabbix documentation

Discussion Forum and Topics

Each NMS we looked into has a discussion forum for the user to ask and answer questions to the community. The discussions are grouped by topic/tag for the user to filter or search for the information they need. Magma's Slack channel enables the users to communicate with each other, but it is not the best way to find topics or answers to questions in a structured way.

Ubiquity discussion forum and tags

OpenNMS discussion forum

Users can subscribe to the questions they want to follow

Suggesting New Features

Another cool thing the user can do on the discussion forum is suggesting new features. If they like a feature someone else has suggested, they can show their support by 'Liking' it. This creates opportunities for the community to benefit and support each other. Developers from the community can gain inspirations on what features to create, and other community members could possibly get the feature they need.

Feature requests on LibreNMS discussion forum

Documentation Structure

The structure of the documentation can be generally categorized into the following sections

• Introduction (overview, definition)
• Deployment (installation, getting started, setup)
• Operation (configuration, use of the platform such as monitoring, alerting, API)
• Development (setup environment, code guidelines, creating documentation)
• Appendix (FAQ, reference material)

Side-by-side navigation structure of LibreNMS, OpenNMS, and Zabbix

Recommendations for Magma's Documentation

• Audit the current documentation. This will help us list out the content that we need to add or improve.
• Enable the community to contribute to the documentation. Community members can either help us improve the quality of the documentation, or create new content when they develop new features.
• Streamline the publishing process. Align the publishing timeline with the product releases and make documentation an integral part of the product development process.
• Define templates. Define the structure and guidelines to ensure the consistency of the language and content.
• Use a forum for discussion. Group the conversations into different topics so that it's easy to find answers to questions.

[Neudrino]

I think https://github.com/magma/magma/issues/9848 should be mentioned for reference here. I wonder if this supersedes or conflicts with #9848?

[Neudrino]

Was the Magma documentation also analysed to see, which of the recommendations is already met or which of the components and features are already available?

[Neudrino]

One point not covered so far is the Documentation distribution.

For Magma documentation seems to be rather distributed to several places, including

• DocuSaurus: https://docs.magmacore.org/docs/basics/introduction.html
• Github Wiki: https://github.com/magma/magma/wiki
• Confluence :question: (There was a confluence announced some-when, however, I am not sure if it was decided yet.)
• Documentation of "parallel organisation", e.g. https://docs.magmaindia.org/index.html

[iirisgao]

I think #9848 should be mentioned for reference here. I wonder if this supersedes or conflicts with #9848?

Thanks for mentioning this issue, just added it to the proposal. This should be additions to #9848 hopefully, not conflicts with it.

[iirisgao]

One point not covered so far is the Documentation distribution.

For Magma documentation seems to be rather distributed to several places, including

• DocuSaurus: https://docs.magmacore.org/docs/basics/introduction.html
• Github Wiki: https://github.com/magma/magma/wiki
• Confluence ❓ (There was a confluence announced some-when, however, I am not sure if it was decided yet.)
• Documentation of "parallel organisation", e.g. https://docs.magmaindia.org/index.html

Great point on the distribution. Looks like the the user guide in on DocuSaurus and the contributor guide is on GitHub. I don't have enough context about why we keep them separate. But one single place for documentation would be ideal, if that's possible.

[andreilee]

Great point of comparison between the more traditional discussion forums and our use of Slack, as well as the downsides we face with Slack. I think if that's something we can add without much overhead, we should go for it.

[stale[bot]]

This pull request has been automatically marked as stale because it has not had any recent activity by the author or maintainer in the past 45 days. It will be closed if no further activity occurs in the next 7 days. Thank you for your contributions.

[lucasgonze]

This improvement does not have the urgency to dedicate extremely limited hours to it. However, it could be reopened if a contributor wants to take it over the finish line.