diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/contributing-documentation.md | 109 | ||||
| -rw-r--r-- | docs/contributing/style-guide.md | 128 |
2 files changed, 61 insertions, 176 deletions
diff --git a/docs/contributing/contributing-documentation.md b/docs/contributing/contributing-documentation.md deleted file mode 100644 index da28272b4..000000000 --- a/docs/contributing/contributing-documentation.md +++ /dev/null @@ -1,109 +0,0 @@ -<!-- -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 ---> - -# 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](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. - -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. - -## Before you get started - -Anyone interested in contributing to documentation should first read the [Netdata style -guide](https://github.com/netdata/netdata/blob/master/docs/contributing/style-guide.md) and the [Netdata Community Code of Conduct](https://github.com/netdata/.github/blob/main/CODE_OF_CONDUCT.md). - -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. - -### 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](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 under the **Reference** section in the Netdata Learn sidebar. -- **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://github.com/netdata/netdata/blob/master/docs/cloud/cloud.mdx`](https://github.com/netdata/netdata/blob/master/docs/cloud/cloud.mdx). -- **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`. - -## 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](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](https://github.com/netdata/netdata/blob/master/docs/contributing/style-guide.md) -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](#making-a-pull-request) 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](https://github.com/netdata/netdata) and -clicking on the **Fork** button. - - - -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 -``` - -Create a new branch using `git checkout -b BRANCH-NAME`. Use your favorite text editor to make your changes, keeping the -[Netdata style guide](https://github.com/netdata/netdata/blob/master/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. - -## Making a pull request - -Pull requests (PRs) should be concise and informative. See our [PR guidelines](https://learn.netdata.cloud/contribute/handbook#pr-guidelines) for -specifics. - -- 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. - -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](https://learn.netdata.cloud) to publish the -changed documentation. - - diff --git a/docs/contributing/style-guide.md b/docs/contributing/style-guide.md index 7d1b86478..997bc61a8 100644 --- a/docs/contributing/style-guide.md +++ b/docs/contributing/style-guide.md @@ -1,19 +1,14 @@ -<!-- -title: "Netdata style guide" -description: "The Netdata style guide establishes editorial guidelines for all of Netdata's writing, including documentation, blog posts, in-product UX copy, and more." -custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/contributing/style-guide.md ---> - # Netdata style guide -The _Netdata style guide_ establishes editorial guidelines for any writing produced by the Netdata team or the Netdata -community, including documentation, articles, in-product UX copy, and more. Both internal Netdata teams and external -contributors to any of Netdata's open-source projects should reference and adhere to this style guide as much as -possible. +The _Netdata style guide_ establishes editorial guidelines for any writing produced by the Netdata team or the Netdata community, including documentation, articles, in-product UX copy, and more. + +> ### Note +> This document is meant to be accompanied by the [Documentation Guidelines](https://github.com/netdata/netdata/blob/master/docs/guidelines.md). If you want to contribute to Netdata's documentation, please read it too. + +Both internal Netdata teams and external contributors to any of Netdata's open-source projects should reference and adhere to this style guide as much as possible. -Netdata's writing should **empower** and **educate**. You want to help people understand Netdata's value, encourage them -to learn more, and ultimately use Netdata's products to democratize monitoring in their organizations. To achieve these -goals, your writing should be: +Netdata's writing should **empower** and **educate**. You want to help people understand Netdata's value, encourage them to learn more, and ultimately use Netdata's products to democratize monitoring in their organizations. +To achieve these goals, your writing should be: - **Clear**. Use simple words and sentences. Use strong, direct, and active language that encourages readers to action. - **Concise**. Provide solutions and answers as quickly as possible. Give users the information they need right now, @@ -353,56 +348,6 @@ The Netdata team uses [`remark-lint`](https://github.com/remarkjs/remark-lint) f If you want to see all the settings, open the [`remarkrc.js`](https://github.com/netdata/netdata/blob/master/.remarkrc.js) file in the `netdata/netdata` repository. -### Frontmatter - -Every document must begin with frontmatter, followed by an H1 (`#`) heading. - -Unlike typical Markdown frontmatter, Netdata uses HTML comments (`<!--`, `-->`) to begin and end the frontmatter block. -These HTML comments are later converted into typical frontmatter syntax when building [Netdata -Learn](https://learn.netdata.cloud). - -Frontmatter _must_ contain the following variables: - -- A `title` that quickly and distinctly describes the document's content. -- A `description` that elaborates on the purpose or goal of the document using no less than 100 characters and no more - than 155 characters. -- A `custom_edit_url` that links directly to the GitHub URL where another user could suggest additional changes to the - published document. - -Some documents, like the Ansible guide and others in the `/docs/guides` folder, require an `image` variable as well. In -this case, replace `/docs` with `/img/seo`, and then rebuild the remainder of the path to the document in question. End -the path with `.png`. A member of the Netdata team will assist in creating the image when publishing the content. - -For example, here is the frontmatter for the guide -about [deploying the Netdata Agent with Ansible](https://github.com/netdata/netdata/blob/master/docs/guides/deploy/ansible.md). - -```markdown -<!-- -title: Deploy Netdata with Ansible -description: "Deploy an infrastructure monitoring solution in minutes with the Netdata Agent and Ansible. Use and customize a simple playbook for monitoring as code." -image: /img/seo/guides/deploy/ansible.png -custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/guides/deploy/ansible.md ---> - -# Deploy Netdata with Ansible - -... -``` - -Questions about frontmatter in -documentation? [Ask on our community forum](https://community.netdata.cloud/c/blog-posts-and-articles/6). - -### Linking between documentation - -Documentation should link to relevant pages whenever it's relevant and provides valuable context to the reader. - -Links should always reference the full path to the document, beginning at the root of the Netdata Agent repository -(`/`), and ending with the `.md` file extension. Avoid relative links or traversing up directories using `../`. - -For example, if you want to link to our node configuration document, link -to `https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md`. To reference -the guide for deploying the Netdata Agent with Ansible, link to `/docs/guides/deploy/ansible.md`. - ### References to UI elements When referencing a user interface (UI) element in Netdata, reference the label text of the link/button with Markdown's @@ -464,6 +409,58 @@ inline char *health_stock_config_dir(void) { Prism also supports titles and line highlighting. See the [Docusaurus documentation](https://v2.docusaurus.io/docs/markdown-features#code-blocks) for more information. +### Adding Notes + +Notes inside files should render properly both in GitHub and in Learn, to do that, it is best to use the format listed below: + +``` +> ### Note +> This is an info or a note block. + +> ### Tip, Best Practice +> This is a tip or a best practice block. + +> ### Warning, Caution +> This is a warning or a caution block. +``` + +Which renders into: + + +> ### Note +> This is an info or a note block. + +> ### Tip, Best Practice +> This is a tip or a best practice block. + +> ### Warning, Caution +> This is a warning or a caution block. + +### Tabs + +Docusaurus allows for Tabs to be used, but we have to ensure that a user accessing the file from GitHub doesn't notice any weird artifacts while reading. So, we use tabs only when necessary in this format: + +``` + +<Tabs> +<TabItem value="tab1" label="tab1"> + +<h3> Header for tab1 </h3> + +text for tab1, both visible in GitHub and Docusaurus + + +</TabItem> +<TabItem value="tab2" label="tab2"> + +<h3> Header for tab2 </h3> + +text for tab2, both visible in GitHub and Docusaurus + +</TabItem> +</Tabs> +``` + ## Word list The following tables describe the standard spelling, capitalization, and usage of words found in Netdata's writing. @@ -476,7 +473,6 @@ The following tables describe the standard spelling, capitalization, and usage o | **Netdata** | The company behind the open-source Netdata Agent and the Netdata Cloud web application. Never use _netdata_ or _NetData_. <br /><br />In general, focus on the user's goals, actions, and solutions rather than what the company provides. For example, write _Learn more about enabling alarm notifications on your preferred platforms_ instead of _Netdata sends alarm notifications to your preferred platforms_. | | **Netdata Agent** | The free and open source [monitoring agent](https://github.com/netdata/netdata) that you can install on all of your distributed systems, whether they're physical, virtual, containerized, ephemeral, and more. The Agent monitors systems running Linux, Docker, Kubernetes, macOS, FreeBSD, and more, and collects metrics from hundreds of popular services and applications. | | **Netdata Cloud** | The web application hosted at [https://app.netdata.cloud](https://app.netdata.cloud) that helps you monitor an entire infrastructure of distributed systems in real time. <br /><br />Never use _Cloud_ without the preceding _Netdata_ to avoid ambiguity. | -| **Netdata community** | Contributors to any of Netdata's [open-source projects](https://github.com/netdata/learn/blob/master/contribute/projects.mdx), members of the [community forum](https://community.netdata.cloud/). | | **Netdata community forum** | The Discourse-powered forum for feature requests, Netdata Cloud technical support, and conversations about Netdata's monitoring and troubleshooting products. | | **node** | A system on which the Netdata Agent is installed. The system can be physical, virtual, in a Docker container, and more. Depending on your infrastructure, you may have one, dozens, or hundreds of nodes. Some nodes are _ephemeral_, in that they're created/destroyed automatically by an orchestrator service. | | **Space** | The highest level container within Netdata Cloud for a user to organize their team members and nodes within their infrastructure. A Space likely represents an entire organization or a large team. <br /><br />_Space_ is always capitalized. | @@ -489,7 +485,5 @@ The following tables describe the standard spelling, capitalization, and usage o | Term | Definition | |-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **filesystem** | Use instead of _file system_. | -| **preconfigured** | The concept that many of Netdata's features come with sane defaults that users don't need to configure to find [immediate value](https://github.com/netdata/netdata/blob/master/docs/overview/why-netdata.md#simple-to-deploy). | +| **preconfigured** | The concept that many of Netdata's features come with sane defaults that users don't need to configure to find immediate value. | | **real time**/**real-time** | Use _real time_ as a noun phrase, most often with _in_: _Netdata collects metrics in real time_. Use _real-time_ as an adjective: _Netdata collects real-time metrics from hundreds of supported applications and services. | - - |