diff options
Diffstat (limited to 'docs/contributing/contributing-documentation.md')
| -rw-r--r-- | docs/contributing/contributing-documentation.md | 235 |
1 files changed, 76 insertions, 159 deletions
diff --git a/docs/contributing/contributing-documentation.md b/docs/contributing/contributing-documentation.md index ebdffdbf6..44be92299 100644 --- a/docs/contributing/contributing-documentation.md +++ b/docs/contributing/contributing-documentation.md @@ -1,192 +1,109 @@ -# Contributing to documentation - -We welcome contributions to Netdata's already extensive documentation, -which we host at [docs.netdata.cloud](https://docs.netdata.cloud/) -and store inside of the [main repository](https://github.com/netdata/netdata) on GitHub. - -Like all contributing to all other aspects of Netdata, we ask that anyone who wants to help with documentation -read and abide by the [Contributor Convenant Code of Conduct](https://docs.netdata.cloud/code_of_conduct/) -and follow the instructions outlined in our [Contributing document](../../CONTRIBUTING.md). - -We also ask you to read our [documentation style guide](style-guide.md), which, while not complete, -will give you some guidance on how we write and organize our documentation. - -All our documentation uses the Markdown syntax. If you're not familiar with how it works, -please read the [Markdown introduction post](https://daringfireball.net/projects/markdown/) by its creator, -followed by [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub. +<!-- +title: "Contributing to documentation" +description: "Want to contribute to Netdata's documentation? This guide will set you up with the tools to help others learn about health and performance monitoring." +custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/contributing/contributing-documentation.md +--> -## How contributing to the documentation works - -There are two ways to contribute to Netdata's documentation: +# Contributing to documentation -1. Edit documentation [directly in GitHub](#edit-documentation-directly-on-github). -2. Download the repository and [edit documentation locally](#edit-documentation-locally). +We welcome contributions to Netdata's already extensive documentation. -Editing in GitHub is a simpler process and is perfect for quick edits to a single document, -such as fixing a typo or clarifying a confusing sentence. +We store documentation related to the open-source Netdata Agent inside of the [`netdata/netdata` +repository](https://github.com/netdata/netdata) on GitHub. Documentation related to Netdata Cloud is stored in a private +repository and is not currently open to community contributions. -Editing locally is more complex, as you need to download the Netdata repository -and build the documentation using `mkdocs`, but allows you to better organize complex projects. -By building documentation locally, you can preview your work using a local web server before you submit your PR. +The Netdata team aggregates and publishes all documentation at [learn.netdata.cloud](https://learn.netdata.cloud/) using +[Docusaurus](https://v2.docusaurus.io/) in a private GitHub repository. -In both cases, you'll finish by submitting a pull request (PR). -Once you submit your PR, GitHub will initiate a number of jobs, including a Netlify preview. -You can use this preview to view the documentation site with your changes applied, -which might help you catch any lingering issues. +## Before you get started -To continue, follow one of the paths below: +Anyone interested in contributing to documentation should first read the [Netdata style +guide](/docs/contributing/style-guide.md) and the [Netdata Community Code of Conduct](/CODE_OF_CONDUCT.md). -- [Edit documentation directly in GitHub](#edit-documentation-directly-on-github) -- [Edit documentation locally](#edit-documentation-locally) +Netdata's documentation uses Markdown syntax. If you're not familiar with Markdown, read the [Mastering +Markdown](https://guides.github.com/features/mastering-markdown/) guide from GitHub for the basics on creating +paragraphs, styled text, lists, tables, and more. -## Edit documentation directly on GitHub +### Netdata's documentation structure -Start editing documentation on GitHub by clicking the small pencil icon on any page on Netdata's [documentation site](https://docs.netdata.cloud/). -You can find them at the top of every page. +Netdata's documentation is separated into four sections. -Clicking on this icon will take you to the associated page in the `netdata/netdata` repository. -Then click the small pencil icon on any documentation file (those ending in the `.md` Markdown extension) in the `netdata/netdata` repository. +- **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](https://github.com/netdata/netdata/tree/master/docs) 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`](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`](https://learn.netdata.cloud/docs/agent). +- **Netdata Cloud reference**: Reference documentation for the closed-source Netdata Cloud web application. + - Stored in a private GitHub repository and not editable by the community. + - Published at [`https://learn.netdata.cloud/docs/cloud`](https://learn.netdata.cloud/docs/cloud). +- **Guides**: Solutions-based articles for users who want instructions on completing a specific complex task using the + Netdata Agent and/or Netdata Cloud. + - Stored in the [`/docs/guides` folder](https://github.com/netdata/netdata/tree/master/docs/guides) within the + `netdata/netdata` repository. Organized into subfolders that roughly correlate with the core Netdata documentation. + - Published at [`https://learn.netdata.cloud/guides`](https://learn.netdata.cloud/guides). - +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`. -If you know where a file resides in the Netdata repository already, -you can skip the step of beginning on the documentation site and go directly to GitHub. +## How to contribute -Once you've clicked the pencil icon on GitHub, you'll see a full Markdown version of the file. -Make changes as you see fit. -You can use the `Preview changes` button to ensure your Markdown syntax is working properly. +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. -Under the `Propose file change` header, write in a descriptive title for your requested change. -Beneath that, add a concise descrition of what you've changed and why you think it's important. Then, click the `Propose file change` button. +Click on the **Edit this page** button on any published document on [Netdata Learn](https://learn.netdata.cloud). 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](/docs/contributing/style-guide.md) +in mind, and use *Preview changes** button to ensure your Markdown syntax works as expected. -After you've hit that button, -jump down to our instructions on [pull requests and cleanup](#pull-requests-and-final-steps) for your next steps. +Under the **Commit changes** header, write descriptive title for your requested change. Click the **Commit changes** +button to initiate your pull request (PR). -!!! note - This process will create a branch directly on the `netdata/netdata` repository, which then requires manual cleanup. - If you're going to make significant documentation contributions, or contribute often, - we recommend the local editing process just below. +Jump down to our instructions on [PRs](#making-a-pull-request) for your next steps. -## Edit documentation locally +### Edit locally -Editing documentation locally is the preferred method for complex changes, PRs that span across multiple documents, -or those that change the styling or underlying functionality of the documentation. +Editing documentation locally is the preferred method for complex changes that span multiple documents or change the +documentation's style or structure. -Here is the workflow for editing documentation locally. First, create a fork of the Netdata repository, -if you don't have one already. Visit the [Netdata repository](https://github.com/netdata/netdata) -and click on the `Fork` button in the upper-right corner of the window. +Create a fork of the Netdata Agent repository by visit the [Netdata repository](https://github.com/netdata/netdata) and +clicking on the **Fork** button. - + -GitHub will ask you where you want to clone the repository, -and once finished you'll end up at the index of your forked Netdata repository. -Clone your fork to your local machine: +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: ```bash git clone https://github.com/YOUR-GITHUB-USERNAME/netdata.git ``` -You can now jump into the directory and explore Netdata's structure for yourself. - -### Understanding the structure of Netdata's documentation - -All of Netdata's documentation is stored within the repository itself, as close as possible to the code it -corresponds to. Many sub-folders contain a `README.md` file, -which is then used to populate the documentation about that feature/component of Netdata. - -For example, the file at `packaging/installer/README.md` becomes `https://docs.netdata.cloud/packaging/installer/` -and is our installation documentation. By co-locating it with quick-start installtion code, -we ensure documentation is always tightly knit with the functions it describes. - -You might find other `.md` files within these directories. The `packaging/installer/` folder also contains `UPDATE.md` -and `UNINSTALL.md`, which become `https://docs.netdata.cloud/packaging/installer/update/` -and `https://docs.netdata.cloud/packaging/installer/uninstall/`, respectively. - -If the documentation you're working on has a direct correlation to some component of Netdata, place it into the correct -folder and either name it `README.md` for generic documentation, or with another name for very specific instructions. - -#### The `docs` folder - -At the root of the Netdata repository is a `docs/` folder. Inside this folder we place documentation that does not have -a direct relationship to a specific component of Netdata. It's where we house our [getting started -guide](../../docs/getting-started.md), guides on [running Netdata behind Nginx](../../docs/Running-behind-nginx.md), and -more. - -If the documentation you're working on doesn't have a direct relaionship to a component of Netdata, -it can be placed in this `docs/` folder. - -### Make your edits - -Now that you're set up and understand where to find or create your `.md` file, you can now begin to make your edits. -Just use your favorite editor and keep in mind our [style guide](style-guide.md) as you work. - -If you add a new file to the documentation, you may need to modify the `buildyaml.sh` file to ensure -it's added to the site's navigation. This is true for any file added to the `docs/` folder. - -Be sure to periodically add/commit your edits so that you don't lose your work! -We use version control software for a reason. - -### Build the documentation - -Building the documentation periodically gives you a glimpse into the final product, and is generally required -if you're making changes to the table of contents. - -!!! attention "" - We have only tested the build process on Linux. Initial tests on OS X have been unsuccessful. - Windows is fully untested at this point, but we would love to know if it works there as well! - -To build the documentation, you need `python`/`pip`, `mkdocs`, and `mkdocs-material` installed on your machine. - -Follow the [Python installation instructions](https://www.python.org/downloads/) for your machine. - -Use `pip`, which was installed alongside Python, to install `mkdocs` and `mkdocs-material`. -Your operating system might force you to use `pip2` or `pip3` instead, -dependin on which version of Python you have installed. - -```bash -pip install mkdocs mkdocs-material -``` - -??? note "Troubleshooting" - If you're having trouble with the installation of Python, `mkdocs`, or `mkdocs-material`, try looking into the `mkdocs` [installation instructions](https://squidfunk.github.io/mkdocs-material/getting-started/#installation). - -When `pip` is finished installing, navigate to the root directory of the Netdata repository -and run the documentation generator script. - -```bash -sh docs/generator/buildhtml.sh -``` - -This process will take some time. Once finished, the built documentation site will be located at `docs/generator/build/`. - -### Run a local web server to test documentation - -The best way to view the documentation site you just built is to run a simple web server from the `docs/generator/build/` directory. -So, navigate there and run a Python-based web server: - -```sh -cd docs/generator/build/ -python3 -m http.server 20000 -``` - -Feel free to replace the port number you want this web server to listen on (port `20000` in this case (only one higher -than the agent!)). - -Open your web browser and navigate to `http://localhost:20000`. -If you replaced the port earlier, change it here as well. -You can now navigate through the documentation as you would on the live site! +Create a new branch using `git checkout -b BRANCH-NAME`. Use your favorite text editor to make your changes, keeping the +[Netdata style guide](/docs/contributing/style-guide.md) in mind. Add, commit, and push changes to your fork. When +you're finished, visit the [Netdata Agent Pull requests](https://github.com/netdata/netdata/pulls) to create a new pull +request based on the changes you made in the new branch of your fork. -## Pull requests and final steps +## Making a pull request -When you're finished with your changes, add and commit them to your fork of the Netdata repository. -Head over to GitHub to create your pull request (PR). +Pull requests (PRs) should be concise and informative. See our [PR guidelines](/CONTRIBUTING.md#pr-guidelines) for +specifics. -Once we receive your pull request (PR), we'll take time to read through it and assess it for correctness, conciseness, -and overall quality. -We may point to specific sections and ask for additional information or other fixes. +- The title must follow the [imperative mood](https://en.wikipedia.org/wiki/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. -## What's next +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. -- Read up on the Netdata documentation [style guide](style-guide.md). +After merging your PR, the Netdata team rebuilds the [documentation site](https://learn.netdata.cloud) to publish the +changed documentation. [](<>) |