Skip to content

Latest commit

 

History

History
232 lines (163 loc) · 11.6 KB

WRITERS-NOTES.md

File metadata and controls

232 lines (163 loc) · 11.6 KB

Writer's Notes

Formatting

  • Line wrapping: Most files don't use line wrapping. Each paragraph or sentence is a complete string of text without newline characters. The rationale is that most viewers and editors have configurable soft-wrap abilities, and every author tends to choose a different hard-wrap column.

Admonitions

Admonitions use a combined MkDocs/Bootstrap definition to get acceptable and similar rendering on both Percona.com (Drupal-based) and Render.com.

Percona.com uses Bootstrap 4. Admonitions are styled as Alerts.

Material for MkDocs theme: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types

General advice

Admonitions are to highlight something special, not to make every point significant. When used in this way, they are ignored in the same way as 'the boy who cried wolf'. But they help to break up large blocks of text, and add a little colour.

  • Use sparingly.

  • Consider whether the same text can be emphasised with normal means (italics or bold).

Overview

By using a subset of all MkDocs, we can get some alignment between those and Bootstrap.

Admonition MkDocs colour Bootstrap colour
Notes, info Blue Blue
See also Blue Turquoise
Tip Green Green
Caution, Warning, Important Amber Amber
Danger Red Red
Summary Turquoise Turquoise

Note, Info

Use as a side panel, an 'aside', a note detached from the main flow of the text.

Preferred use is without the label (first form).

!!! note alert alert-primary ""
    Text ...

!!! note alert alert-primary "Note"
    Text ...

!!! note alert alert-primary "Side topic"
    Text ...

Caution, Warning, Important

Uses same type but different label text:

  • Caution: Used to mean 'Continue with care'. Less strong than 'Warning' IMHO.

  • Important: A significant point that deserves emphasis. (MkDocs default for 'important' admonition is green, which is why I don't use it.)

Style:

  • MkDocs: Amber with triangle/! icon
  • Bootstrap: Yellow with no icon
!!! caution alert alert-warning "Caution"
!!! caution alert alert-warning "Important"

Danger

Anything that has the potential to damage or compromise a user's data or system.

  • MkDocs: Red with bolt icon.
  • Boostrap: Red with no icon.
!!! danger alert alert-danger "Danger"

Tip

Use for tips, hints, non-essential but useful advice. Note that tip renders badly in Percona.com. hint is better and looks the same as tip in Material theme.

!!! hint alert alert-success "Tip"
    Tip

!!! hint alert alert-success "Tips"
    - One
    - Two

!!! hint alert alert-success ""
    Tip

Summary

Used to summarise a block of text (a TLDR).

!!! summary alert alert-info "Summary"

See Also

Used to highlight other sections or external links.

Group them at the end of the section.

An exception would be when there is an equivalent or closely related section elsewhere.

  • MkDocs: Blue with pen icon (same as note).
  • Bootstrap: Turquoise with no icon.
!!! seealso alert alert-info "See also"

Variables

We use the mkdocs-macros plugin for variable expansion. For example, the variable release in variables.yml is used in the code so that the current PMM release number is always up-to-date. (Search the markdown files for {{release}}.)

This plugin can have problems when Jinja-like constructs are used in code. This happens when referring to Docker variables. Workarounds are explained here: https://github.com/fralau/mkdocs_macros_plugin/blob/master/webdoc/docs/advanced.md#solutions

In some places, we have used variables themselves to solve the problem. In others, {% raw %}/{% endraw %} surrounds the conflicting text.

Icons

Use HTML for icons:

Unicons icon code Description Used where
Down chevron PMM UI
Four boxes in square PMM UI - QAN
Left arrow PMM UI
3 horizontal lines PMM UI - HA dashboards
Bell PMM UI - Alerting
Lightening flash/bolt PMM UI - Nodes compare
Right caret General
Clock (at nine) PMM UI - Time range selector
Cog wheel PMM UI Configuration
Share comment symbol PMM UI - Share dashboard image
Compass PMM UI - Explore
Copy PMM UI - Copy (e.g. backup schedule)
Cube PMM UI
Database PMM UI DBaaS symbol
Vertical ellipsis PMM UI column menus
Exclamation mark in triangle PMM UI - Warnings
Eye with slash PMM UI Password hide
Eye PMM UI Password reveal
File symbol PMM UI - Home dashboard
3-bar chart PMM UI link to dashboard
Backward arrow circle around clock PMM UI - Backups and checks
List PMM UI - Alert rules
Computer monitor PMM UI - Cycle view mode
Pen PMM UI - Edit
Plus within circle PMM UI Inventory->Add Instance
Plus within square PMM UI - Add
Question mark in circle PMM UI - Help
Minus in magnifying glass PMM UI - Time range zoom out
Magnifying glass PMM UI - Search
Cog wheel PMM UI Configuration->Settings
Share symbol PMM UI - Share dashboard
Shield PMM UI - Server admin
Star PMM UI - Dashboard favourites
Twin backward arrows PMM UI - Refresh dashboard
Hand, thumbs down For Benefits/Drawbacks tables
Hand, thumbs up For Benefits/Drawbacks tables
Large 'X' PMM UI
Toggle (off) PMM UI - Toggle switch
Toggle (on) PMM UI - Toggle switch
Trash can PMM UI - Various 'Delete' operation

Custom (in-house design) icons are defined as SVG code in variables.yml.

Usage Description Used where
{{icon.addinstance}} Thin + in circle PMM Add Instance
{{icon.checks}} Checkbox list items Inventory list
{{icon.inventory}} Checkbox list items PMM Inventory & Inventory List
{{icon.dashboards}} Abstract blocks assembly PMM Dashboards
{{icon.node}} Circle surrounded by smaller circles Node dashboards
{{icon.percona}} Percona logo Wherever PMM home icon is needed

Symbols

While MkDocs will automatically replace certain strings with symbols, it's preferable where possible to use unicode symbols for other icons, so that they appear when the raw Markdown is exported as HTML and imported into Google Docs.

For Use
-->

Language

We have attempted to eschew traditional terminology used in software manuals. Some examples:

  • "Setting up" instead of "installation and configuration"
  • "Before you start" instead of "Prerequisites"

There are no "introduction" or "overview" sections. These texts are just there under the title.

Section titles are deliberately short. For example, in Setting up/Server/Docker, the 'Run' section shows how to run the docker image for PMM Server. The docs are for 'PMM', the section is 'Server' and subsection 'Docker'. That's what we're running.

Numbered lists

Most Markdown processors automatically number lists when they are like this:

1. Item
1. Item
1. Item
   ...

But to make the raw Markdown easier to read, we recommend explicitly numbering items:

1. Item
2. Item
3. Item
   ...

Other advantages:

  • contents can be reused in source code comments by developers;
  • encourages authors to pay attention to the order and number of steps in a recipe.