docs: contributing updates (#41836)

* contributing updates first draft

* ran yarn prettier

* updated links

* removed test xref

* Update contribute/documentation/README.md

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>

Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>

CONTRIBUTING.md

@@ -46,6 +46,10 @@ If you have an idea of how to improve Grafana, submit an [enhancement request](h
 
 We want to make Grafana accessible to even more people. Submit an [accessibility issue](https://github.com/grafana/grafana/issues/new?labels=type%3A+accessibility&template=3-accessibility.md) to help us understand what we can improve.
 
+### Write documentation
+
+To edit or write technical content, refer to [Contribute to our documentation](/contribute/documentation/README.md). We welcome your expertise and input as our body of technical content grows.
+
 ### Triage issues
 
 If you don't have the knowledge or time to code, consider helping with _issue triage_. The community will thank you for saving them time by spending some of yours.

contribute/README.md

@@ -3,7 +3,7 @@
 This directory contains guides for contributors to the Grafana project.
 
 - [Create a pull request](create-pull-request.md)
-- [Contributing documentation](documentation.md)
+- [Contribute documentation](../contribute/documentation/README.md)
 - [Developer guide](developer-guide.md)
 - [Triage issues](triage-issues.md)
 - [Merge a pull request](merge-pull-request.md)

contribute/documentation.md

@@ -1,42 +0,0 @@
-# Contributing to documentation
-
-This documents guides you through the process of contributing to the Grafana documentation. Make sure you've read the guide for [Contributing to Grafana](/CONTRIBUTING.md).
-
-## Your first contribution
-
-If you’re unsure about where to start, check out some of our [open docs issues](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fdocs).
-
-Sometimes it can be difficult to understand an issue when you're just getting started. Refer to this list of [beginner-friendly issues](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fdocs+label%3A"beginner+friendly") for tasks suitable for first-time contributors.
-
-When you’ve found an issue you want to work on, please comment on the issue to let other people know you intend to work on it.
-
-If you encounter any misspellings or violations to the style guide, please let us know by submitting an issue (or just fix them if they are minor changes).
-
-On every page in the [documentation](https://grafana.com/docs/) are two links in the upper right corner:
-
-- **Edit this page** takes you directly to the file on GitHub where you can contribute a fix.
-- **Request doc changes** prepares an issue on GitHub with relevant information already filled in.
-
-## Join our community
-
-For general discussions on documentation, you’re welcome to join the `#docs` channel on our [public Grafana Slack](http://slack.raintank.io) team.
-
-## Style and formatting
-
-All Grafana documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown), and can be found in the [docs](/docs) directory in the [Grafana GitHub repository](https://github.com/grafana/grafana). The [documentation website](https://grafana.com/docs) is generated with [Hugo](https://gohugo.io) which uses [Blackfriday](https://github.com/russross/blackfriday) as its Markdown rendering engine.
-
-### Documentation structure
-
-The Grafana documentation is organized into topics, called _sections_. You can take a look at the current build at [grafana.com/docs/](https://grafana.com/docs/).
-
-Each top-level section is located under the [docs/sources](/docs/sources) directory. Subsections are added by creating a subdirectory in the directory of the parent section.
-
-For each section, an `_index.md` file provides an overview of the topic.
-
-### Style guide
-
-Refer to the [Documentation style guide](style-guides/documentation-style-guide.md) for information about Grafana style, word choice, and grammar conventions.
-
-### Spelling
-
-The [codespell](https://github.com/codespell-project/codespell) tool is run for every change to catch common misspellings.

contribute/documentation/README.md

@@ -0,0 +1,235 @@
+# Contribute to our documentation
+
+We provide these guidelines to help our contributors make additions or corrections to our documentation.
+
+## Welcome
+
+Welcome. We're glad you're here to help make our technical documentation even better. We develop content that leads our users to success using Grafana products. Technical accuracy is our primary consideration, and we value the use of inclusive language. We regard your feedback as a gift - thanks for reading through these guidelines.
+
+### Intended audience
+
+We write these guidelines for contributors who are interested in improving our technical content.
+
+## Understanding the structure of Grafana documentation
+
+All Grafana Enterprise and OSS documentation is located in the [Grafana open source project](https://github.com/grafana/grafana) GitHub repository: https://github.com/grafana/grafana/tree/main/docs/sources.
+
+- The **sources** directory organizes content by topic areas, for example **administration** and **alerting**.
+- Topic directories include an `_index.md` file, which provides an overview of the topic, and optionally includes subtopics that provide more detail.
+
+> The `_index.md` file is required.
+
+### Writing in markdown
+
+We write technical documentation using [Markdown](https://en.wikipedia.org/wiki/Markdown). We've put together a short guide to help you how to structure and format your content.
+
+To access the markdown guide, refer to [Markdown style guide](documentation-markdown-guide.md).
+
+## Ways to contribute
+
+We're thrilled that you are considering contributing to the documentation. You can contribute content in the following ways:
+
+- [Request a change](#request-a-change)
+- [Edit a topic](#edit-a-topic)
+- [Write a topic](#write-a-topic)
+
+### Request a change
+
+Request a change when you want to make a suggestion about a topic, but don't want to provide an edit that generates a pull request. Requesting a change gives you the freedom to express your ideas without committing language. Your suggestion can reflect a small change to wording or can reflect larger, more substantive changes.
+
+GitHub captures your request as an **Issue** logged against the repository.
+
+Before you begin:
+
+- Create a GitHub account.
+
+To request a change, complete the following steps:
+
+1.  While viewing the topic, click **Request a change**.
+
+The Issue title auto-populates with the location of the file about which you are requesting a change.
+
+![Request a change](request-change.png)
+
+2. Enter a change request description.
+
+3. Add the **type/docs** label.
+
+4. Click **Submit new issue**.
+
+### Edit a topic
+
+If you want to recommend a small change, such as suggesting a correction to a topic, you can edit the topic directly in GitHub. You are not required to fork and clone the repo to use this approach.
+
+Other small changes might include:
+
+- Adding steps to a task
+- Adding clarifying language to a concept
+- Providing an example
+
+Before you begin:
+
+- Create a GitHub account.
+
+To edit a topic, complete the following steps:
+
+1. While viewing the topic you want to edit, click **Edit this page**.
+
+![Edit a topic](edit-file.png)
+
+2. Add your changes to the topic.
+
+3. Scroll to the bottom of the page and enter a branch name.
+
+   For example, enter `clarified dashboard panel definition`.
+
+4. Click **Commit**.
+
+   GitHub prompts you to create a PR.
+
+5. Complete the prompts provided in the body of the PR.
+
+6. Click **Create pull request**.
+
+### Write a topic
+
+At Grafana Labs, we use the principles of topic-based authoring when we write technical documentation. Topic-based authoring provides guidelines for writing three _types_ of technical documentation: concept, task, and reference. Before you begin writing, establish the topic type you want to write.
+
+#### Understanding topic types
+
+Technical content is divided into three topic types: concept, task, and reference.
+
+- **Concept**: A concept topic explains _what_ a feature (or idea) is, and why it is important.
+- **Task**: A task topic explains _how_ to complete an end user procedure in the system. Task topics contain steps.
+- **Reference** A reference topic contains lookup information that a user might consult when they complete a task. Documenting a list of values with descriptions is a common form of reference topic.
+
+**Example**
+
+Suppose you are writing content for a site called _Doggie handbook_. You might organize your topics like this:
+
+**Concepts**
+
+- What a dog is
+- Brief history of dogs
+- Why you might want a dog
+- Tasks dogs can be trained to do
+
+**Tasks**
+
+- Feed the dog
+- Groom the dog
+- Train the dog
+
+**References**
+
+- List of dog equipment you will need
+- Table of breeds that includes breed name, size range, short or long hair, and type of dog
+
+#### Prepare your environment
+
+Before you begin writing, we recommend that you fork and clone the Grafana repository so that you can use a text editor locally to create branches, commit your changes, and create a PR.
+
+While this document doesn't include git commands or descriptions of Github operations, you might find these links useful.
+
+- [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git): We store all source code, including documentation, in Git repositories.
+- [Fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo): Locate the repo you want to clone, and fork it.
+- [Clone a repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository): Clone the repository to your local machine.
+- [Create a branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging): Before you make change, create a branch. Do not push changes against the `main` branch.
+- [Create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request): After you add, commit, and push your changes, create a PR in Github.
+
+#### Use a documentation template to contribute a topic
+
+We have provided documentation templates that align with each topic type:
+
+- [Concept](templates/doc-concept-template.md)
+- [Task](templates/doc-task-template.md)
+- [Reference](templates/doc-reference-template.md)
+
+Each template provides additional usage and formatting guidelines. We recommend that you make a copy of whichever template you are using, then add content.
+
+> Remove any unused content before you commit your changes.
+
+#### View a local build
+
+Prior to pushing your changes, you can view a local build of the documentation so that you can review your work.
+
+To view a local build:
+
+1. Install [Docker](https://www.docker.com/products/docker-desktop).
+
+1. Run Docker.
+
+1. Navigate to the **docs** root directory.
+
+1. Run `make build`.
+
+1. Open `localhost:3002` to review your changes.
+
+## Push changes and create a PR
+
+When you are ready for other people to review your work, perform the following tasks.
+
+1. [Add](https://git-scm.com/docs/git-add) your changes, which prepares your content for the next commit.
+
+1. [Commit](https://git-scm.com/docs/git-commit) your changes.
+
+1. [Push](https://git-scm.com/docs/git-push) your changes to Github.
+
+1. [Create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) in Github.
+
+The docs build system automatically conducts a series of tests to ensure that the content doesn't conflict with other content in the docs repository.
+
+### Understanding the PR review and approval workflow
+
+When a PR is added to the repo with a label associated with `docs`, it will be reviewed by a member of the technical writing team. Depending on the size of the PR and the priority of other work, the PR will either be immediately reviewed and merged (minor fixes typically follow this pattern) or the PR will be triaged and placed in the backlog of work or moved into further development.
+
+## Join our community
+
+For general discussions on documentation, you’re welcome to join the `#docs` channel on our [public Grafana Slack](http://slack.raintank.io) team.
+
+## Reference: Top five writing tips
+
+While we don't provide a comprehensive style guide in this document, here's a few writing tips to help the writing process.
+
+### Consider the audience
+
+Write for an audience that is computer literate and has general technical knowledge, but is not necessarily familiar with Grafana or the finer points of observability.
+
+Pretend you are explaining your topic to a brand new Grafana user or developer.
+
+### Write clear and concise sentences and paragraphs
+
+Use the following sentence structure when you write: _subject_—_verb_—_object_. If you are telling a user to do something, write an imperative sentence. For example “Enter the refresh rate time interval and click Save.”
+
+- You can also start a sentence with an _if_ clause, which positions the condition before the action.
+- Limit the number of words in a sentence to 20..
+
+### Use active voice
+
+Active voice makes the performer of the action the subject
+of the sentence. When you write in passive voice, the recipient of the action (and not the performer) becomes the subject of the sentence.
+
+Active-voice sentences are more direct and clearly identify _who_ is doing _what_. Not all tasks are completed by a user; sometimes the system can also be a performer (and by extension, the subject of the sentence). When you write in active voice you clearly make that distinction, which results in more engaging and less wordy content.
+
+| Use (active)                                          | Avoid (passive)                                                      |
+| ----------------------------------------------------- | -------------------------------------------------------------------- | --- |
+| After you upgrade the software, restart the computer. | After the software has been upgraded, the computer can be restarted. |
+| Click **OK** to save the dashboard.                   | The dashboard is saved when the **OK** button is clicked.            |
+| Create a dashboard.                                   | A dashboard is created by you.                                       | .   |
+
+### Avoid obscure non-English words and abbreviations
+
+Users might be unfamiliar with some non-English words and abbreviations such as _per_, _vs_, and _via_. Latin abbreviations in particular, like _i.e._, _e.g._, and _etc._, are vague.
+
+| Use          | Don’t use   |
+| ------------ | ----------- |
+| through      | via         |
+| that is      | i.e.        |
+| according to | per, as per |
+| and so on    | etc.        |
+
+### Write self-contained topics
+
+Thanks to search engines, every page in the documentation might be a reader's entry point. This means that each page needs to be self-contained and make sense on its own. The reader should not need to read other topics in order to perform the task or understand the concept.
+
+However, try to be helpful and link to related information. Using the _Doggie handbook_ example, the concept topic that explains what dogs can be trained to do might link to the Train the dog task.

contribute/style-guides/documentation-style-guide.md

@@ -119,7 +119,7 @@ If that is the case, then use the following format for headings:
 - Assume all graphics will be exclusively viewed on the web.
 - Maximum image size is 3840px X 2160px.
 - Screenshots should be readable, but not too large.
-- _Do not_ use image shortcodes. Follow the guidance in the [Grafana markdown guide](https://github.com/grafana/grafana/blob/main/contribute/style-guides/documentation-markdown-guide.md#images).
+- _Do not_ use image shortcodes. Follow the guidance in [Markdown style guide](../documentation/documentation-markdown-guide.md#Images).
 - Markdown image links are preferred. Only use the HTML image links if you need to style the image in ways unsupported in Markdown.
 - When you name a file, follow the [file naming conventions](#file-naming-conventions). Example: image-name-7-3.png
 

contribute/templates/README.md

@@ -1,60 +0,0 @@
-# Templates
-
-Templates are both a starting point and an instruction manual for writing something new. They are intended to make life easier by providing a jumping-off point, something besides a blank page to start from. They are not intended to be a limitation. If the template does not work perfectly for your use case, you can adjust or change it. We will work it out in code review.
-
-## Create a template
-
-Feel free to add templates to the `templates` folder. Try to make them as generic as possible and include clear instructions for when and how to use the template. Assume that the template user is a brand new contributor and write accordingly.
-
-## Use a template
-
-1. Read the template. Make sure you understand what it is for and how it is intended to be used.
-1. Copy and rename the template. Move it to where you actually need it.
-   You might also want to copy the content of the template and paste it into a different file. This is acceptable use.
-1. Replace the template content with your own. Delete whatever is unnecessary.
-
-## Documentation templates
-
-In an ideal world, each topic will correspond to an information _type_ ([task](doc-task-template.md), [reference](doc-reference-template.md), [concept](doc-concept-template.md)) and contain only that type of information.
-
-However, this is not always practical. For example, you have a series of short topics, you can group them into one topic.
-
-Try to _chunk_ your content. This means you should organize the document so that the same kinds of content are grouped together.
-
-### Chunking example
-
-If I was writing content for a site called _Doggie handbook_, I might organize it like this.
-
-**Concept**
-
-- What a dog is
-- Brief history of dogs
-- Why you might want a dog
-- Tasks dogs can be trained to do
-
-**Tasks**
-
-- Feed the dog
-- Groom the dog
-- Train the dog
-
-**Reference**
-
-- List of dog equipment you will need
-- Table of breeds that includes breed name, size range, short or long hair, and type of dog
-
-### Audience
-
-Write for an audience that is computer literate and has general technical knowledge, but is not necessarily familiar with Grafana or the finer points of observability.
-
-Pretend you are explaining your topic to a brand new Grafana user or developer.
-
-### Self-contained
-
-Thanks to search engines, every page in the documentation might be a reader's entry point. This means that each page needs to be self-contained and make sense on its own. The reader should not need to read other topics in order to perform the task or understand the concept.
-
-However, try to be helpful and link to related information. Using the _Doggie handbook_ example, the concept topic that explains what dogs can be trained to do might link to the Train the dog task.
-
-## Code templates
-
-This is a placeholder for future templates.