diff --git a/style_guides/README.md b/style_guides/README.md new file mode 100644 index 00000000000..bd777ed2519 --- /dev/null +++ b/style_guides/README.md @@ -0,0 +1,9 @@ +# Style guides + +This section contains style guides for the Grafana software project and documentation. + +- [Backend style guide](https://github.com/grafana/grafana/blob/master/pkg/STYLEGUIDE.md): Provides guidance on how to style and format backend functionality and code. +- [Documentation style guide](documentation-style-guide.md): Provides guidance on how to style and format documentation. +- [Frontend style guide](frontend.md): Provides guidance on how to style and format the user-facing functionality and code. +- [Redux framework](redux.md): Provides guidance on designing the Grafana redux framework. +- [Themes style guide](themes.md): Provides guidance on designing and updating Grafana themes. \ No newline at end of file diff --git a/style_guides/documentation-style-guide.md b/style_guides/documentation-style-guide.md new file mode 100644 index 00000000000..7698cdfc9f2 --- /dev/null +++ b/style_guides/documentation-style-guide.md @@ -0,0 +1,62 @@ +# Documention style guide + +This style guide applies to all documentation created for Grafana products. + +## Contributing + +This style guide is a living document. Add to it whenever a style decision is made or question is answered. + +## Published guides + +For all items not covered in this guide, refer to the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) and the [Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html). + +## Grafana-specific style + +### General + +* Use active voice. Avoid passive voice. + - Passive: The heatmap visualization is displayed. + - Active: Grafana displays the heatmap visualization. +* Write in the imperative second person. Examples: You can write a query. Click the panel. Close the window. +* Write in present tense. + - Not: The panel will open. + - Use: The panel opens. Grafana opens the panel. + +### File naming conventions + +- Files that are displayed in the help system should have names that are all lowercase, no spaces. Use hyphens instead of spaces. Example: glossary.md +- Documentation file names should match the title. **Note:** This only applies to new files at this time. Do not change the names of older files unless directed to do so. +- Internal reference file names should be all uppercase except the file extension. Example: CONTRIBUTING.md + +### Headings + +* Write headings in sentence case, not title case. + - This is sentence case + - This Is Title Case +* Task topic headings start with a verb. + - Write a query. Create a dashboard. +* Concept and reference topic headings should be nouns or gerunds. Examples: Contributing to docs, Visualizations, Style guide + +### Images + +* Preferred format is .png +* File extension should be all lowercase. +* Preferred DPI is 72. +* 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. + +### Capitalization + +* Grafana, Loki, and Prometheus are always capitalized unless part of a code block. +* Abbreviations are always capitalized (such as HTTP or URL) + +### Word usage +Grafana products has some words, abbreviations, and slang particular to this discourse commmunity. + +#### data source +Two words, not one + +**Exceptions:** +* "datasource" used as an identifier +* "datasource" in a URL diff --git a/style_guides/frontend.md b/style_guides/frontend.md index be43738f6f3..2f7828bfa37 100644 --- a/style_guides/frontend.md +++ b/style_guides/frontend.md @@ -4,19 +4,17 @@ Generally we follow the Airbnb [React Style Guide](https://github.com/airbnb/jav ## Table of Contents -1. [Basic Rules](#basic-rules) -1. [File & Component Organization](#Organization) -1. [Naming](#naming) -1. [Declaration](#declaration) -1. [Props](#props) -1. [Refs](#refs) -1. [Methods](#methods) -1. [Ordering](#ordering) -1. [State mangement](#State-mangement) +- [Frontend Style Guide](#frontend-style-guide) + - [Table of Contents](#table-of-contents) + - [Basic rules](#basic-rules) + - [Organization](#organization) + - [Props](#props) + - [State mangement](#state-mangement) ## Basic rules -- Try to keep files small and focused and break large components up into sub components. +- Try to keep files small and focused. +- Break large components up into sub-components. ## Organization @@ -31,7 +29,7 @@ Generally we follow the Airbnb [React Style Guide](https://github.com/airbnb/jav ## Props -- Name callback props & handlers with a "on" prefix. +- Name callback props and handlers with an "on" prefix. ```tsx // good