Skip to content
Snippets Groups Projects
Commit 53b0c241 authored by Sean Madsen's avatar Sean Madsen
Browse files

Increase granularity of docs style guide headings

This makes it easier to refer people to specific guidelines within the
guide.
parent 0924b81a
No related branches found
No related tags found
1 merge request!503Docs style guide changes and improvements
...@@ -5,34 +5,48 @@ high-quality "finished" [documentation](/documentation/index.md) ...@@ -5,34 +5,48 @@ high-quality "finished" [documentation](/documentation/index.md)
about CiviCRM. This Style Guide page documents the standards we wish to about CiviCRM. This Style Guide page documents the standards we wish to
uphold to ensure all guides maintain this high level of quality. uphold to ensure all guides maintain this high level of quality.
## Parts, chapters, sections ## General guidelines
Similar to most text books and manuals, we divide our guides into "parts", ### Docs nomenclature {:#nomenclature}
"chapters", and "sections". In mkdocs, these blocks translate as follows:
To streamline communication about documentation issues, we define the following terms:
- "part" - folder - "part" - folder
- "chapter" - file (in markdown), also one web page with a given URL - "chapter" - file (in markdown), also one web page with a given URL
- "section" - heading within the page - "section" - heading within the page
### Menu depth
In the navigation menu (as stored in `mkdocs.yml`): In the navigation menu (as stored in `mkdocs.yml`):
- Keep the page hierarchy to the depth described above - keep the page hierarchy to the depth described above
(i.e. do not put folders within other folders). (i.e. do not put folders within other folders).
### Chapter names
In the navigation menu (as stored in `mkdocs.yml`):
- Each chapter name should be short enough to fit nicely in the menu, - Each chapter name should be short enough to fit nicely in the menu,
but also long enough to stand on its own to a reasonable extent. but also long enough to stand on its own to a reasonable extent.
The titles set here are used in the navigation menu *and* the page title The titles set here are used in the navigation menu *and* the page title
that displays in the browser tab. The guide will be more usable if the that displays in the browser tab. The guide will be more usable if the
reader sees two tabs titled "Using Hooks" and "API Usage" instead of reader sees two tabs titled "Using Hooks" and "API Usage" instead of
"Usage" and "Usage". "Usage" and "Usage".
### Introductory paragraphs
Each chapter should start with a paragraph that explains what will be Each chapter should start with a paragraph that explains what will be
covered in the chapter. covered in the chapter.
### Cumulative concepts
Effort should be given to arrange all content within a guide so that skills and Effort should be given to arrange all content within a guide so that skills and
concepts which build upon one another are presented sequentially. concepts which build upon one another are presented sequentially.
Although guides should not require start-to-finish reading, providing the Although guides should not require start-to-finish reading, providing the
option (when possible) is helpful to some readers. option (when possible) is helpful to some readers.
### Cross-references
Don't use terms like "previous chapter", etc. because we may add or re-arrange Don't use terms like "previous chapter", etc. because we may add or re-arrange
chapters in the future. Instead, use a hyperlink to the chapter. chapters in the future. Instead, use a hyperlink to the chapter.
...@@ -47,14 +61,14 @@ in H2 and H3, only where necessary. If you find yourself wanting to use ...@@ -47,14 +61,14 @@ in H2 and H3, only where necessary. If you find yourself wanting to use
H4, consider if it's truly necessary and whether the chapter should H4, consider if it's truly necessary and whether the chapter should
instead be refactored. instead be refactored.
### Capitalization ### Title capitalization
Titles for parts, chapters, and sections should all be in sentence case Titles for parts, chapters, and sections should all be in sentence case
(first word capitalized), not headline case (each word capitalized). (first word capitalized), not headline case (each word capitalized).
## Formatting conventions ## Describing the CiviCRM user interface
### Describing the CiviCRM user interface ### Bold for things you click
Menu selections, buttons, tabs (basically, things that the reader is Menu selections, buttons, tabs (basically, things that the reader is
being told to click) should be in bold. being told to click) should be in bold.
...@@ -66,6 +80,8 @@ For example: ...@@ -66,6 +80,8 @@ For example:
- Modify event type labels by clicking **Edit** on any row. - Modify event type labels by clicking **Edit** on any row.
- Click **Add Event Type** to create a new category for your events. - Click **Add Event Type** to create a new category for your events.
### UI element capitalization
Elements of the system and interface should be capitalized (e.g. the Elements of the system and interface should be capitalized (e.g. the
Events component, the Template Title field). Events component, the Template Title field).
...@@ -78,13 +94,19 @@ thing or technical definition (e.g. scheduled reminders, plain text). ...@@ -78,13 +94,19 @@ thing or technical definition (e.g. scheduled reminders, plain text).
Use your best judgment as to what serves the reader; trying to enforce Use your best judgment as to what serves the reader; trying to enforce
consistency in this arena will slow us down or drive us crazy. consistency in this arena will slow us down or drive us crazy.
### Quotes
Quotes should be avoided as much as possible; however, do use them when Quotes should be avoided as much as possible; however, do use them when
they seem necessary for clarity (e.g. if you are talking about setting they seem necessary for clarity (e.g. if you are talking about setting
or field labels that are long phrases). or field labels that are long phrases).
### Types of CiviCRM pages
You can divide the CiviCRM interface into administration pages and You can divide the CiviCRM interface into administration pages and
public-facing pages. public-facing pages.
## Formatting conventions
### Bullets and numbered lists ### Bullets and numbered lists
Bulleted lists should be used to convey short snippets of information. Bulleted lists should be used to convey short snippets of information.
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment