From aa2fe8ccbfcb117efa207d10229eeeac5d0f97c7 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 Feb 2023 17:11:30 +0100 Subject: Adding upstream version 1.38.0. Signed-off-by: Daniel Baumann --- docs/contributing/contributing-documentation.md | 8 +- docs/contributing/style-guide.md | 101 ++++++++++++------------ 2 files changed, 56 insertions(+), 53 deletions(-) (limited to 'docs/contributing') diff --git a/docs/contributing/contributing-documentation.md b/docs/contributing/contributing-documentation.md index 68b861d40..da28272b4 100644 --- a/docs/contributing/contributing-documentation.md +++ b/docs/contributing/contributing-documentation.md @@ -18,7 +18,7 @@ The Netdata team aggregates and publishes all documentation at [learn.netdata.cl ## Before you get started 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](https://learn.netdata.cloud/contribute/code-of-conduct). +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 @@ -40,7 +40,7 @@ Netdata's documentation is separated into four sections. - 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://learn.netdata.cloud/docs/cloud`](https://learn.netdata.cloud/docs/cloud). + - 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 @@ -59,7 +59,7 @@ fixes to a single document, such as fixing a typo or clarifying a confusing sent 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) +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** @@ -86,7 +86,7 @@ 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](/docs/contributing/style-guide.md) in mind. Add, commit, and push changes to your fork. When +[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. diff --git a/docs/contributing/style-guide.md b/docs/contributing/style-guide.md index 5ff61164d..7d1b86478 100644 --- a/docs/contributing/style-guide.md +++ b/docs/contributing/style-guide.md @@ -67,8 +67,8 @@ Netdata is a global company in every sense, with employees, contributors, and us communicate in a way that is clear and easily understood by everyone. Here are some guidelines, pointers, and questions to be aware of as you write to ensure your writing is universal. Some -of these are expanded into individual sections in the [language, grammar, and -mechanics](#language-grammar-and-mechanics) section below. +of these are expanded into individual sections in +the [language, grammar, and mechanics](#language-grammar-and-mechanics) section below. - Would this language make sense to someone who doesn't work here? - Could someone quickly scan this document and understand the material? @@ -97,8 +97,8 @@ mechanics](#language-grammar-and-mechanics) section below. To ensure Netdata's writing is clear, concise, and universal, we have established standards for language, grammar, and certain writing mechanics. However, if you're writing about Netdata for an external publication, such as a guest blog -post, follow that publication's style guide or standards, while keeping the [preferred spelling of Netdata -terms](#netdata-specific-terms) in mind. +post, follow that publication's style guide or standards, while keeping +the [preferred spelling of Netdata terms](#netdata-specific-terms) in mind. ### Active voice @@ -106,31 +106,32 @@ Active voice is more concise and easier to understand compared to passive voice. the sentence is action. In passive voice, the subject is acted upon. A famous example of passive voice is the phrase "mistakes were made." -| | | -|-----------------|---------------------------------------------------------------------------------------------| -| Not recommended | When an alarm is triggered by a metric, a notification is sent by Netdata. | -| **Recommended** | When a metric triggers an alarm, Netdata sends a notification to your preferred endpoint. | +| | | +|-----------------|-------------------------------------------------------------------------------------------| +| Not recommended | When an alarm is triggered by a metric, a notification is sent by Netdata. | +| **Recommended** | When a metric triggers an alarm, Netdata sends a notification to your preferred endpoint. | ### Second person -Use the second person ("you") to give instructions or "talk" directly to users. +Use the second person ("you") to give instructions or "talk" directly to users. In these situations, avoid "we," "I," "let's," and "us," particularly in documentation. The "you" pronoun can also be -implied, depending on your sentence structure. +implied, depending on your sentence structure. One valid exception is when a member of the Netdata team or community wants to write about said team or community. -| | | -|--------------------------------|-------------------------------------------------------------------------------------------| -| Not recommended | To install Netdata, we should try the one-line installer... | -| **Recommended** | To install Netdata, you should try the one-line installer... | -| **Recommended**, implied "you" | To install Netdata, try the one-line installer... | +| | | +|--------------------------------|--------------------------------------------------------------| +| Not recommended | To install Netdata, we should try the one-line installer... | +| **Recommended** | To install Netdata, you should try the one-line installer... | +| **Recommended**, implied "you" | To install Netdata, try the one-line installer... | ### "Easy" or "simple" -Using words that imply the complexity of a task or feature goes against our policy of [universal -communication](#universal-communication). If you claim that a task is easy and the reader struggles to complete it, you -may inadvertently discourage them. +Using words that imply the complexity of a task or feature goes against our policy +of [universal communication](#universal-communication). If you claim that a task is easy and the reader struggles to +complete it, you +may inadvertently discourage them. However, if you give users two options and want to relay that one option is genuinely less complex than another, be specific about how and why. @@ -163,11 +164,11 @@ See the [word list](#word-list) for spellings of specific words. Follow the general [English standards](https://owl.purdue.edu/owl/general_writing/mechanics/help_with_capitals.html) for capitalization. In summary: -- Capitalize the first word of every new sentence. -- Don't use uppercase for emphasis. (Netdata is the BEST!) -- Capitalize the names of brands, software, products, and companies according to their official guidelines. (Netdata, - Docker, Apache, NGINX) -- Avoid camel case (NetData) or all caps (NETDATA). +- Capitalize the first word of every new sentence. +- Don't use uppercase for emphasis. (Netdata is the BEST!) +- Capitalize the names of brands, software, products, and companies according to their official guidelines. (Netdata, + Docker, Apache, NGINX) +- Avoid camel case (NetData) or all caps (NETDATA). Whenever you refer to the company Netdata, Inc., or the open-source monitoring agent the company develops, capitalize **Netdata**. @@ -244,10 +245,10 @@ must reflect the _current state of [production](https://app.netdata.cloud). Every link should clearly state its destination. Don't use words like "here" to describe where a link will take your reader. -| | | -|-----------------|-------------------------------------------------------------------------------------------| -| Not recommended | To install Netdata, click [here](/packaging/installer/README.md). | -| **Recommended** | To install Netdata, read the [installation instructions](/packaging/installer/README.md). | +| | | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| Not recommended | To install Netdata, click [here](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md). | +| **Recommended** | To install Netdata, read the [installation instructions](https://github.com/netdata/netdata/blob/master/packaging/installer/README.md). | Use links as often as required to provide necessary context. Blog posts and guides require less hyperlinks than documentation. See the section on [linking between documentation](#linking-between-documentation) for guidance on the @@ -268,7 +269,7 @@ and desired audience. ## Technical/Linux standards Configuration or maintenance of the Netdata Agent requires some system administration skills, such as navigating -directories, editing files, or starting/stopping/restarting services. Certain processes +directories, editing files, or starting/stopping/restarting services. Certain processes ### Switching Linux users @@ -302,16 +303,17 @@ Netdata Agent installation will have commands under the same paths. When applica path, providing a recommendation or instructions on how to view the running configuration, which includes the correct paths. -For example, the [configuration](/docs/configure/nodes.md) doc first teaches users how to find the Netdata config +For example, the [configuration](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md) doc first +teaches users how to find the Netdata config directory and navigate to it, then runs commands from the `/etc/netdata` path so that the instructions are more universal. Don't include full paths, beginning from the system's root (`/`), as these might not work on certain systems. -| | | -|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Not recommended | Use `edit-config` to edit Netdata's configuration: `sudo /etc/netdata/edit-config netdata.conf`. | -| **Recommended** | Use `edit-config` to edit Netdata's configuration by first navigating to your [Netdata config directory](/docs/configure/nodes.md#the-netdata-config-directory), which is typically at `/etc/netdata`, then running `sudo edit-config netdata.conf`. | +| | | +|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Not recommended | Use `edit-config` to edit Netdata's configuration: `sudo /etc/netdata/edit-config netdata.conf`. | +| **Recommended** | Use `edit-config` to edit Netdata's configuration by first navigating to your [Netdata config directory](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory), which is typically at `/etc/netdata`, then running `sudo edit-config netdata.conf`. | ### `sudo` @@ -371,8 +373,8 @@ Some documents, like the Ansible guide and others in the `/docs/guides` folder, 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://learn.netdata.cloud/guides/deploy/ansible). +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