Skip to content

doc_styleguide.md

Latest commit

 

History

History
66 lines (45 loc) · 1.86 KB

doc_styleguide.md

File metadata and controls

66 lines (45 loc) · 1.86 KB

Documentation Style Guide

Prefer only markdown elements and avoid HTML tags if possible. This makes the content easier to maintain and more transferable.

Emojis

  • Emojis are a great way to recognise content quickly.
  • Use them if a content is used often.
  • Try not overuse them.

External Links

It is polite to warn readers if they leave the current page. They can choose to open the link in a new tab if they want to. Use the ↗ before the link, e.g.: ↗ SprintEins

Expandable Content

In markdown you can use the HTML ↗ details tag.

Use this for content that you do not want to read every time, such as:
  • screenshots that help in tutorials
  • additional descriptions that explain something that you only must read once
  • install steps that the user does not need but good if it is needed. e.g.: "how to install git"
  • etc...

Tables

Use tables for data and not for styling. It is not 1990s.

Admonition

Admonition help draw attention to content. Use it for extra information, tips, and warnings.

Templates

  • Warning

    ⚠️ Warning: This is really important! Sometimes only warnings have an "icon" to emphasize their importance

    > **⚠️ Warning:** This is really important!
> Sometimes only warning have an "icon" to emphasize their importance

  • Info

    ℹ️ Info: This is just additional information, maybe a link to another documentation. They can be multi-line.

    > **ℹ️ Info:** This is just additional information, maybe a link to another documentation.
> They can be multi-line.

  • Tip

    ✅ Tip: This is a helpful tip.

    > **✅ Tip:** This is a helpful tip.