DRAFT: Update OpenNMS Documentation

Motivation

Now that we have successfully migrated our documentation to Antora, it’s time to update the content. Our goal is to implement a more task-based approach to what is documented, restructure content where appropriate to streamline it for accessibility, and fix those typos! This could include moving some content to reference sections, or, as in the case of Ronny’s work in the deployment section, changing the way information is presented to minimize scrolling through long pages of text.

If you want to say hi or let us know how you think we can improve the docs, you can talk to Bonnie (gromit) and Ronny (indigo) in the Write the Docs channel in our Mattermost.

Project Review/Restructure Status

  • :o: Horizon/Meridian (@Bonrob, @indigo)
    :building_construction: Welcome [:woman_technologist:]
    • :o: Software overview - needs technical review
  • :building_construction: Deployment
    * :o: Horizon/Minion using gRPC
    * :o: Time series storage with RRDTool
    * :o: Time series storage with Newts
    * :o: Install different versions than stable
    * :o: Tuning Kafka
    * :o: Rebuild overview for Core
    * :o: Rebuild overview for Minion
    * :o: Rebuild overview for Sentinel
  • :building_construction: Operation
    • :white_check_mark: Data Choices (Bonnie)
    • :white_check_mark: Users (Bonnie)
    • :o: Provisioning
    • :o: Notifications
    • :o: Service Assurance
    • :o: Performance Management
    • :o: Business Service Monitoring
    • :o: Events
    • :o: Alarms
    • :o: Metadata
    • :o: Third-Party Integration
      • :o: Ticketing
    • :o: Elasticsearch Integration
    • :white_check_mark: Thresholding (Bonnie)
    • :o: Web UI may remove this in final version
    • :o: Toplogy Map
    • :o: Asset Toplology Provider
    • :o: Database Reports
    • :o: Enhanced Linkd
    • :o: Open Tracing
    • :o: Operation
    • :o: System Properties
    • :o: Enabling RMI
    • :o: Minion
    • :o: Sentinel
    • :o: Special Cases and Workarounds
    • :o: IFTTT Integration
    • :o: DNS Resolver
    • :o: Telemetry Daemon
    • :o: Flow support
    • :o: Kafka Producer
    • :o: Alarm Correlation (need ALEC)
    • :o: SNMP Interface Poller
    • :o: Administration
    • :building_construction: Development
      • :o: Set up a Development System
      • :o: Minion Development
      • :o: Topology
      • :o: Graph Service API
      • :o: CORS Support
      • :o: REST API
      • :o: Develop Documentation - needs to be massively revised
      • :o: AMQP Integration
      • :o: Design and Style Guidelines
    • :building_construction: Reference
    • :building_construction: Glossary
  • :o: Helm
  • :o: ALEC
  • :o: PRIS
  • :o: OpenNMS.JS

Deliverables

The project is managed in our JIRA in Epic TBD. We follow the “develop” branch which is currently targeting Horizon 28.0.0-SNAPSHOT.
Everything which is pushed to the working branches is pushed nightly with CircleCI to docs.opennms.com.

If you are impatient and you want to trigger the build + publish job immediately you need an account to access the CircleCI build job and click [ Rerun workflow from start ] on the “nightly” build.

How to Contribute

The branch TBD represents the whole epic migrating everything to Antora. We follow develop 28.0.0-SNAPSHOT.

Step 1: Create an issue (Story) with the topic you want to work on from above. Assign your story to the epic .

Step 2: Create a branch based on TBD and do some work

Step 3: Give us a Pull Request against the TBD branch for review and merge