Skip to content

Latest commit

 

History

History
109 lines (80 loc) · 6.6 KB

contributing-documentation.md

File metadata and controls

109 lines (80 loc) · 6.6 KB
Raw

Contributing to documentation

We welcome contributions to Netdata's already extensive documentation.

We store documentation related to the open-source Netdata Agent inside of the netdata/netdata repository on GitHub. Documentation related to Netdata Cloud is stored in a private repository and is not currently open to community contributions.

The Netdata team aggregates and publishes all documentation at learn.netdata.cloud using Docusaurus in a private GitHub repository.

Before you get started

Anyone interested in contributing to documentation should first read the Netdata style guide and the Netdata Community Code of Conduct.

Netdata's documentation uses Markdown syntax. If you're not familiar with Markdown, read the Mastering Markdown guide from GitHub for the basics on creating paragraphs, styled text, lists, tables, and more.

Netdata's documentation structure

Netdata's documentation is separated into four sections.

  • Netdata: Documents based on the actions users want to take, and solutions to their problems, such both the Netdata Agent and Netdata Cloud.
    • Stored in various subfolders of the /docs folder within the netdata/netdata repository: /docs/collect, /docs/configure, /docs/export, /docs/get, /docs/monitor, /docs/overview, /docs/quickstart, /docs/store, and /docs/visualize.
    • Published at https://learn.netdata.cloud/docs.
  • Netdata Agent reference: Reference documentation for the open-source Netdata Agent.
    • Stored in various .md files within the netdata/netdata repository alongside the code responsible for that feature. For example, the database engine's reference documentation is at /database/engine/README.md.
    • Published at https://learn.netdata.cloud/docs/agent.
  • Netdata Cloud reference: Reference documentation for the closed-source Netdata Cloud web application.
  • Guides: Solutions-based articles for users who want instructions on completing a specific complex task using the Netdata Agent and/or Netdata Cloud.

Generally speaking, if you want to contribute to the reference documentation for a specific Netdata Agent feature, find the appropriate .md file co-located with that feature. If you want to contribute documentation that spans features or products, or has no direct correlation with the existing directory structure, place it in the /docs folder within netdata/netdata.

How to contribute

The easiest way to contribute to Netdata's documentation is to edit a file directly on GitHub. This is perfect for small fixes to a single document, such as fixing a typo or clarifying a confusing sentence.

Click on the Edit this page button on any published document on Netdata Learn. Each page has two of these buttons: One beneath the table of contents, and another at the end of the document, which take you to GitHub's code editor. Make your suggested changes, keeping Netdata style guide in mind, and use Preview changes* button to ensure your Markdown syntax works as expected.

Under the Commit changes header, write descriptive title for your requested change. Click the Commit changes button to initiate your pull request (PR).

Jump down to our instructions on PRs for your next steps.

Edit locally

Editing documentation locally is the preferred method for complex changes that span multiple documents or change the documentation's style or structure.

Create a fork of the Netdata Agent repository by visit the Netdata repository and clicking on the Fork button.

Screenshot of forking the Netdata repository

GitHub will ask you where you want to clone the repository. When finished, you end up at the index of your forked Netdata Agent repository. Clone your fork to your local machine:

git clone https://github.com/YOUR-GITHUB-USERNAME/netdata.git

Create a new branch using git checkout -b BRANCH-NAME. Use your favorite text editor to make your changes, keeping the Netdata style guide in mind. Add, commit, and push changes to your fork. When you're finished, visit the Netdata Agent Pull requests to create a new pull request based on the changes you made in the new branch of your fork.

Making a pull request

Pull requests (PRs) should be concise and informative. See our PR guidelines for specifics.

  • The title must follow the imperative mood and be no more than ~50 characters.
  • The description should explain what was changed and why. Verify that you tested any code or processes that you are trying to change.

The Netdata team will review your PR and assesses it for correctness, conciseness, and overall quality. We may point to specific sections and ask for additional information or other fixes.

After merging your PR, the Netdata team rebuilds the documentation site to publish the changed documentation.

analytics