merge guideline docs and add info to style guidedocs-guidelines

3 files changed, 93 insertions, 867 deletions

diff --git a/contribution-guidelines.md b/contribution-guidelines.md
deleted file mode 100644
index d81e0d03be..0000000000
--- a/contribution-guidelines.md
+++ /dev/null
@@ -1,807 +0,0 @@
-# Docs Development Guidelines
-
-Welcome to our docs developer guidelines!
-
-We store documentation related to Netdata inside of
-the [`netdata/netdata` repository](https://github.com/netdata/netdata) on GitHub.
-
-The Netdata team aggregates and publishes all documentation at [learn.netdata.cloud](/) using
-[Docusaurus](https://v2.docusaurus.io/) over at the [`netdata/learn` repository](https://github.com/netdata/learn).
-
-## Before you get started
-
-Anyone interested in contributing to documentation should first read the [Netdata style guide](#styling-guide) further
-down below 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, and read further down about some special
-occasions [while writing in MDX](#mdx-and-markdown).
-
-### Netdata's Documentation structure
-
-Netdata's documentation is separated into 5 categories.
-
-- **Getting Started**: This section’s purpose is to present “What is Netdata” and for whom is it for while also
-  presenting all the ways Netdata can be deployed. That includes Netdata’s platform support, Standalone deployment,
-  Parent-child deployments, deploying on Kubernetes and also deploying on IoT nodes.
-    - Stored in **WIP**
-    - Published in **WIP**
-- **Concepts**: This section’s purpose is to take a pitch on all the aspects of Netdata. We present the functionality of
-  each component/idea and support it with examples but we don’t go deep into technical details.
-    - Stored in the `/docs/concepts` directory in the `netdata/netdata` repository.
-    - Published in **WIP**
-- **Tasks**: This section's purpose is to break down any operation into a series of fundamental tasks for the Netdata
-  solution.
-    - Stored in the `/docs/tasks` directory in the `netdata/netdata` repository.
-    - Published in **WIP**
-- **References**: This section’s purpose is to explain thoroughly every part of Netdata. That covers settings,
-  configurations and so on.
-    - Stored near the component they refer to.
-    - Published in **WIP**
-- **Collectors References**: This section’s purpose is to explain thoroughly every collector that Netdata supports and
-  it's configuration options.
-    - Stored in stored near the collector they refer to.
-    - Published in **WIP**
-
-## 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 the [Netdata style guide](#styling-guide)
-in mind, and use the ***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](/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.
-
-## Writing Docs
-
-We have three main types of Docs: **References**, **Concepts** and **Tasks**.
-
-### Metadata Tags
-
-All of the Docs however have what we call "metadata" tags. these help to organize the document upon publishing.
-
-So let's go through the different necessary metadata tags to get a document properly published on Learn:
-
-- Docusaurus Specific:\
-  These metadata tags are parsed automatically by Docusaurus and are rendered in the published document. **Note**:
-  Netdata only uses the Docusaurus metadata tags releveant for our documentation infrastructure.
-    - `title: "The title of the document"` : Here we specify the title of our document, which is going to be converted
-      to the heading of the published page.
-    - `description: "The description of the file"`: Here we give a description of what this file is about.
-    - `custom_edit_url: https://github.com/netdata/netdata/edit/master/collectors/COLLECTORS.md`: Here is an example of
-      the link that the user will be redirected to if he clicks the "Edit this page button", as you see it leads
-      directly to the edit page of the source file.
-- Netdata Learn specific:
-    - `learn_status: "..."`
-        - The options for this tag are:
-            - `"published"`
-            - `"unpublished"`
-    - `learn_topic_type: "..."`
-        - The options for this tag are:
-            - `"Getting Started"`
-            - `"Concepts"`
-            - `"Tasks"`
-            - `"References"`
-            - `"Collectors References"`
-        - This is the Topic that the file belongs to, and this is going to resemble the start directory of the file's
-          path on Learn for example if we write `"Concepts"` in the field, then the file is going to be placed
-          under `/Concepts/....` inside Learn.
-    - `learn_rel_path: "/example/"`
-        - This tag represents the rest of the path, without the filename in the end, so in this case if the file is a
-          Concept, it would go under `Concepts/example/filename.md`. If you want to place the file under the "root"
-          topic folder, input `"/"`.
-    - ⚠️ In case any of these "Learn" tags are missing or falsely inputted the file will remain unpublished. This is by
-      design to prevent non-properly tagged files from getting published.
-
-While Docusaurus can make use of more metadata tags than the above, these are the minimum we require to publish the file
-on Learn.
-
-### Doc Templates
-
-These are the templates we use for our Documentation files:
-
-<details>
-<summary>Reference Docs</summary>
-
-The template that is used for Reference files is:
-
-```
-  <!--
-  title: "Apache monitoring with Netdata"
-  description: "Monitor the health and performance of Apache web servers with zero configuration, per-second metric granularity, and interactive visualizations."
-  custom_edit_url: https://github.com/netdata/go.d.plugin/edit/master/modules/apache/README.md
-  learn_topic_type: "Collector References"
-  learn_rel_path: "/sample_category"
-  learn_status: "published"
-  -->
-```
-
-## Configuration files
-
-### Data collection
-
-```
-go.d/apache.conf
-```
-
-To make changes, see `the ./edit-config task <link>`
-
-### Alerts
-
-none
-
-## Requirements to run this module
-
-- none
-
-## Requirement on the monitored application
-
-- `Apache` with enabled [`mod_status`](https://httpd.apache.org/docs/2.4/mod/mod_status.html)
-
-## Auto detection
-
-### Single node installation
-
-. . . we autodetect localhost:port and what configurations are defaults
-
-### Kubernetes installations
-
-. . . Service discovery, click here
-
-## Metrics
-
-Columns: Context | description (of the context) | units (of the context) | dimensions | alerts
-
-- Requests in `requests/s`
-- Connections in `connections`
-- Async Connections in `connections`
-- Scoreboard in `connections`
-- Bandwidth in `kilobits/s`
-- Workers in `workers`
-- Lifetime Average Number Of Requests Per Second in `requests/s`
-- Lifetime Average Number Of Bytes Served Per Second in `KiB/s`
-- Lifetime Average Response Size in `KiB`
-
-### Labels
-
-just like <https://github.com/netdata/go.d.plugin/tree/master/modules/k8s_state#labels>
-
-## Alerts
-
-collapsible content for every alert, just like the alert guides
-
-## Configuration options
-
-Table with all the configuration options available.
-
-Columns: name | description | default
-
-## Configuration example
-
-Needs only `url` to server's `server-status?auto`. Here is an example for 2 servers:
-
-```yaml
-jobs:
-  - name: local
-      url: http://127.0.0.1/server-status?auto
-  - name: remote
-      url: http://203.0.113.10/server-status?auto
-```
-
-For all available options please see
-module [configuration file](https://github.com/netdata/go.d.plugin/blob/master/config/go.d/apache.conf).
-
-## Troubleshoot
-
-backlink to the task to run this module in debug mode
-
-</details>
-
-<details>
-<summary>Task Docs</summary>
-
-The template that is used for Task files is:
-
-```
-  <!--
-  title: "Task title"
-  description: "Task description"
-  custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Tasks/sampletask.md
-  learn_topic_type: "Tasks"
-  learn_rel_path: "/sample_category"
-  learn_status: "published"
-  -->
-```
-
-## Description
-
-A small description of the Task.
-
-## Prerequisites
-
-Describe all the information that the user needs to know before proceeding with the task.
-
-## Context
-
-Describe the background information of the Task, the purpose of the Task, and what will the user achieve by completing
-it.
-
-## Steps
-
-A task consists of steps, here provide the actions needed from the user, so he can complete the task correctly.
-
-## Result
-
-Describe the expected output/ outcome of the result.
-
-## Example
-
-Provide any examples needed for the Task
-
-</details>
-
-<details>
-<summary>Concept Docs</summary>
-
-The template of the Concept files is:
-
-```
-  <!--
-  title: "Concept title"
-  description: "Concept description"
-  custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/Concepts/sampleconcept.md
-  learn_topic_type: "Concepts"
-  learn_rel_path: "/sample_category"
-  learn_status: "published"
-  -->
-```
-
-## Description
-
-In our concepts we have a more loose structure, the goal is to communicate the "concept" to the user, starting with
-simple language that even a new user can understand, and building from there.
-
-</details>
-
-## Styling 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.
-
-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,
-  along with opportunities to learn more.
-- **Universal**. Think of yourself as a guide giving a tour of Netdata's products, features, and capabilities to a
-  diverse group of users. Write to reach the widest possible audience.
-
-You can achieve these goals by reading and adhering to the principles outlined below.
-
-## Voice and tone
-
-One way we write empowering, educational content is by using a consistent voice and an appropriate tone.
-
-*Voice* is like your personality, which doesn't really change day to day.
-
-*Tone* is how you express your personality. Your expression changes based on your attitude or mood, or based on who
-you're around. In writing, your reflect tone in your word choice, punctuation, sentence structure, or even the use of
-emoji.
-
-The same idea about voice and tone applies to organizations, too. Our voice shouldn't change much between two pieces of
-content, no matter who wrote each, but the tone might be quite different based on who we think is reading.
-
-For example, a [blog post](https://www.netdata.cloud/blog/) and a [press release](https://www.netdata.cloud/news/)
-should have a similar voice, despite most often being written by different people. However, blog posts are relaxed and
-witty, while press releases are focused and academic. You won't see any emoji in a press release.
-
-### Voice
-
-Netdata's voice is authentic, passionate, playful, and respectful.
-
-- **Authentic** writing is honest and fact-driven. Focus on Netdata's strength while accurately communicating what
-  Netdata can and cannot do, and emphasize technical accuracy over hard sells and marketing jargon.
-- **Passionate** writing is strong and direct. Be a champion for the product or feature you're writing about, and let
-  your unique personality and writing style shine.
-- **Playful** writing is friendly, thoughtful, and engaging. Don't take yourself too seriously, as long as it's not at
-  the expense of Netdata or any of its users.
-- **Respectful** writing treats people the way you want to be treated. Prioritize giving solutions and answers as
-  quickly as possible.
-
-### Tone
-
-Netdata's tone is fun and playful, but clarity and conciseness comes first. We also tend to be informal, and aren't
-afraid of a playful joke or two.
-
-While we have general standards for voice and tone, we do want every individual's unique writing style to reflect in
-published content.
-
-## Universal communication
-
-Netdata is a global company in every sense, with employees, contributors, and users from around the world. We strive to
-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.
-
-- Would this language make sense to someone who doesn't work here?
-- Could someone quickly scan this document and understand the material?
-- Create an information hierarchy with key information presented first and clearly called out to improve scannability.
-- Avoid directional language like "sidebar on the right of the page" or "header at the top of the page" since
-  presentation elements may adapt for devices.
-- Use descriptive links rather than "click here" or "learn more".
-- Include alt text for images and image links.
-- Ensure any information contained within a graphic element is also available as plain text.
-- Avoid idioms that may not be familiar to the user or that may not make sense when translated.
-- Avoid local, cultural, or historical references that may be unfamiliar to users.
-- Prioritize active, direct language.
-- Avoid referring to someone's age unless it is directly relevant; likewise, avoid referring to people with age-related
-  descriptors like "young" or "elderly."
-- Avoid disability-related idioms like "lame" or "falling on deaf ears." Don't refer to a person's disability unless
-  it’s directly relevant to what you're writing.
-- Don't call groups of people "guys." Don't call women "girls."
-- Avoid gendered terms in favor of neutral alternatives, like "server" instead of "waitress" and "businessperson"
-  instead of "businessman."
-- When writing about a person, use their communicated pronouns. When in doubt, just ask or use their name. It's OK to
-  use "they" as a singular pronoun.
-
-> Some of these guidelines were adapted from MailChimp under the Creative Commons license.
-
-## Language, grammar, and mechanics
-
-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.
-
-### Active voice
-
-Active voice is more concise and easier to understand compared to passive voice. When using active voice, the subject of
-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. |
-
-### Second person
-
-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.
-
-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...            |
-
-### "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.
-
-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.
-
-For example, don't write, "Netdata's one-line installer is the easiest way to install Netdata." Instead, you might want
-to say, "Netdata's one-line installer requires fewer steps than manually installing from source."
-
-### Slang, metaphors, and jargon
-
-A particular word, phrase, or metaphor you're familiar with might not translate well to the other cultures featured
-among Netdata's global community. We recommended you avoid slang or colloquialisms in your writing.
-
-In addition, don't use abbreviations that have not yet been defined in the content. See our section on
-[abbreviations](#abbreviations-acronyms-and-initialisms) for additional guidance.
-
-If you must use industry jargon, such as "mean time to resolution," define the term as clearly and concisely as you can.
-
-> Netdata helps you reduce your organization's mean time to resolution (MTTR), which is the average time the responsible
-> team requires to repair a system and resolve an ongoing incident.
-
-### Spelling
-
-While the Netdata team is mostly *not* American, we still aspire to use American spelling whenever possible, as it is
-the standard for the monitoring industry.
-
-See the [word list](#word-list) for spellings of specific words.
-
-### Capitalization
-
-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).
-
-Whenever you refer to the company Netdata, Inc., or the open-source monitoring agent the company develops, capitalize
-**Netdata**.
-
-However, if you are referring to a process, user, or group on a Linux system, use lowercase and fence the word in an
-inline code block: `` `netdata` ``.
-
-|                 |                                                                                                |
-|-----------------|------------------------------------------------------------------------------------------------|
-| Not recommended | The netdata agent, which spawns the netdata process, is actively maintained by netdata, inc.   |
-| **Recommended** | The Netdata Agent, which spawns the `netdata` process, is actively maintained by Netdata, Inc. |
-
-#### Capitalization of document titles and page headings
-
-Document titles and page headings should use sentence case. That means you should only capitalize the first word.
-
-If you need to use the name of a brand, software, product, and company, capitalize it according to their official
-guidelines.
-
-Also, don't put a period (`.`) or colon (`:`) at the end of a title or header.
-
-|                 |                                                                                                     |
-|-----------------|-----------------------------------------------------------------------------------------------------|
-| Not recommended | Getting Started Guide <br />Service Discovery and Auto-Detection: <br />Install netdata with docker |
-| **Recommended** | Getting started guide <br />Service discovery and auto-detection <br />Install Netdata with Docker  |
-
-### Abbreviations (acronyms and initialisms)
-
-Use abbreviations (including [acronyms and initialisms](https://www.dictionary.com/e/acronym-vs-abbreviation/)) in
-documentation when one exists, when it's widely accepted within the monitoring/sysadmin community, and when it improves
-the readability of a document.
-
-When introducing an abbreviation to a document for the first time, give the reader both the spelled-out version and the
-shortened version at the same time. For example:
-
-> Use Netdata to monitor Extended Berkeley Packet Filter (eBPF) metrics in real-time.
-> After you define an abbreviation, don't switch back and forth. Use only the abbreviation for the rest of the document.
-
-You can also use abbreviations in a document's title to keep the title short and relevant. If you do this, you should
-still introduce the spelled-out name alongside the abbreviation as soon as possible.
-
-### Clause order
-
-When instructing users to take action, give them the context first. By placing the context in an initial clause at the
-beginning of the sentence, users can immediately know if they want to read more, follow a link, or skip ahead.
-
-|                 |                                                                                |
-|-----------------|--------------------------------------------------------------------------------|
-| Not recommended | Read the reference guide if you'd like to learn more about custom dashboards.  |
-| **Recommended** | If you'd like to learn more about custom dashboards, read the reference guide. |
-
-### Oxford comma
-
-The Oxford comma is the comma used after the second-to-last item in a list of three or more items. It appears just
-before "and" or "or."
-
-|                 |                                                                              |
-|-----------------|------------------------------------------------------------------------------|
-| Not recommended | Netdata can monitor RAM, disk I/O, MySQL queries per second and lm-sensors.  |
-| **Recommended** | Netdata can monitor RAM, disk I/O, MySQL queries per second, and lm-sensors. |
-
-### Future releases or features
-
-Do not mention future releases or upcoming features in writing unless they have been previously communicated via a
-public roadmap.
-
-In particular, documentation must describe, as accurately as possible, the Netdata Agent _as of
-the [latest commit](https://github.com/netdata/netdata/commits/master) in the GitHub repository_. For Netdata Cloud,
-documentation must reflect the *current state* of [production](https://app.netdata.cloud).
-
-### Informational links
-
-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](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
-Markdown syntax and path structure of inter-documentation links.
-
-### Contractions
-
-Contractions like "you'll" or "they're" are acceptable in most Netdata writing. They're both authentic and playful, and
-reinforce the idea that you, as a writer, are guiding users through a particular idea, process, or feature.
-
-Contractions are generally not used in press releases or other media engagements.
-
-### Emoji
-