From d079b656b4719739b2247dcd9d46e9bec793095a Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 Feb 2023 17:11:34 +0100 Subject: Merging upstream version 1.38.0. Signed-off-by: Daniel Baumann --- docs/contributing/style-guide.md | 101 ++++++++++++++++++++------------------- 1 file changed, 52 insertions(+), 49 deletions(-) (limited to 'docs/contributing/style-guide.md') 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