Presslabs DOCS

Presslabs Markdown Style Guide

What’s better than users knowing how to use our product, without writing to support?! This is why we need a strategy for writing the best documentation we can.

We need to help our users move through our services with great ease and satisfaction. Writing the documentation should feel like giving advice to our best friend. The product is great, now let’s tell our users how to use it.

First things first — what is markdown? It is a plain text formatting syntax, which helps to write structured content for web. It can be easily transformed into HTML.

The Writing Process

Once you finished developing and designing a product, you should then turn your attention on documenting the steps — easy peasy. You have to keep in mind that writing a piece comes with some steps like:

  1. Write — scribble everything that comes into your mind regarding the product or service
  2. Edit — if it doesn’t make sense, it shouldn’t be there
  3. Ask for feedback — at least one other person should check your composition
  4. Publish

The Technique

The entirety of the documentation should be written in the same style and with the same tone of voice.

Language

  • Write in an accessible and friendly manner.
  • Use 1st person plural (we, us, our).
  • Write one idea per sentence, and 3-4 sentences per paragraph.

Structure

  • Intro: Start with title and a short description of the page, and state the main goal
  • Body: Bring arguments to support the main goal
  • Conclusion: Create a compelling ending to your arguments

Strategy

  • Know the audience. In our case — developers (high level), and wannabe developers(low level). Write so that both will understand what you wish to say.
  • Know what are you trying to convey. Always write with the end goal in mind.

Rules

  • Every page should begin with a front matter and one H1 header.
  • Structure information so that you’ll need only three types of heading.
  • After a heading (e.g. H2) don’t proceed with another heading (e.g. H3), a table, or a list.
  • When talking about our dashboard, call it the Presslabs Dashboard instead of Oxygen.
  • Follow the indentation specified below.

The Syntax

The same formatting syntax should be used across all pages. This will create a better experience for our users. Please note the spaces between the elements.

Front Matter

It must be placed on all pages, at the top of the page.

---
title: Page title
linktitle: Link title that appears in navigation if page title too long
description: Page description
keywords: [keywords array separated by comma]
menu:
  global:
    parent: "getting-started"
    weight: 3
aliases: [url slugs separated by comma]
---

Headers

Structure your information so that you will need only 2 headings. The only H1 element on the page is the page title. After the H1 comes the description rendered in a large font paragraph. Other titles used are H2 and H3

H2 title

## Title

H3 title

### Section Title

Strong title

**Paragraph Title**

Text and headers

Use 1 new line above and below the Header.


## Header goes here

Section text goes here [...]

Text and lists

Use 1 new line between heading/paragraph and lists, an indentation of 4 spaces before the list item, and 1 new line before starting another section.

Section text goes here:

    1. List item
    2. List item

Other section text goes here

Text format

Use these:

Text *bold*
Text `code` or `value`

Every wp-admin mention, URLs, variables, keywords, time, etc. should be written in value.

Don’t use these:

Text *italic*
Text ***bold-italic***

Admonitions

The note text should be indented as the note type. Basic note:

> ###### NOTE
>
> Note text goes in here

Other kinds of admonitions:

> ###### WARNING
>
> Note text goes in here

Link

[Link text](link_url)

Images

Always use a descriptive alt. Images must be inside images folder inside markdown file.

![Alternate text here](./fork_windows/fork.png "Alternate text here")