2fb301ccaf
* Move style guides into contribute directory * Move contribution guides into contribute directory * Refactor CONTRIBUTING.md * Clean up docs/README.md * Update reference to style guide and minor formatting fixes * Apply suggestions from code review Co-Authored-By: gotjosh <josue.abreu@gmail.com> * Update CONTRIBUTING.md Co-Authored-By: gotjosh <josue.abreu@gmail.com>
2.7 KiB
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.
Your first contribution
If you’re unsure about where to start, check out some of our open docs issues.
Sometimes it can be difficult to understand an issue when you're just getting started. We strive to keep a collection of beginner-friendly issues that is more suitable for first-time contributors.
When you’ve found an issue you want to work on, you’re encouraged to 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.
On every page in the documentation there are two links:
- 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.
Community
For general discussions on documentation, you’re welcome to join the #docs channel on our public Grafana Slack team.
Guidelines
All Grafana documentation is written using Markdown, and can be found in the docs directory in the Grafana GitHub repository. The documentation website is generated with Hugo which uses Blackfriday as its Markdown rendering engine.
Structure
The documentation is organized into topics, called sections.
Each top-level section is located under the docs/sources directory. Subsections are added by creating a subdirectory in the directory of the parent section.
For each section, a _index.md file is used to provide an overview of the topic.
Style guide
The codespell tool is run for every change to catch common misspellings.
- "Open source" should be hyphenated when used as an adjective, e.g. open-source software. The open form should be preferred when used as a noun, e.g. Grafana is open source.
- Use "data source" instead of "datasource" unless used as an identifier, in code or as part of URLs.
- Acronyms should be uppercased, e.g. URL, DNS, or TCP/IP.