summaryrefslogtreecommitdiffstats
path: root/docs/contributing/contributing-documentation.md
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2021-02-07 11:45:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2021-02-07 11:45:55 +0000
commita8220ab2d293bb7f4b014b79d16b2fb05090fa93 (patch)
tree77f0a30f016c0925cf7ee9292e644bba183c2774 /docs/contributing/contributing-documentation.md
parentAdding upstream version 1.19.0. (diff)
downloadnetdata-a8220ab2d293bb7f4b014b79d16b2fb05090fa93.tar.xz
netdata-a8220ab2d293bb7f4b014b79d16b2fb05090fa93.zip
Adding upstream version 1.29.0.upstream/1.29.0
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/contributing/contributing-documentation.md')
-rw-r--r--docs/contributing/contributing-documentation.md235
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).
-![A screenshot of editing a Markdown file directly in the Netdata repository](https://user-images.githubusercontent.com/1153921/59637188-10426d00-910a-11e9-99f2-ec564d6fb7d5.png)
+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.
-![Screenshot of forking the Netdata repository](https://user-images.githubusercontent.com/1153921/59873572-25f5a380-9351-11e9-92a4-a681fe4a2ed9.png)
+![Screenshot of forking the Netdata
+repository](https://user-images.githubusercontent.com/1153921/59873572-25f5a380-9351-11e9-92a4-a681fe4a2ed9.png)
-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.
[![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Fdocs%2Fcontributing%2Fcontributing-documentation&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>)