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:
- Write — scribble everything that comes into your mind regarding the product or service
- Edit — if it doesn’t make sense, it shouldn’t be there
- Ask for feedback — at least one other person should check your composition
The entirety of the documentation should be written in the same style and with the same tone of voice.
- 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.
- 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
- 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.
- 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 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.
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] ---
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
### Section 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 *bold* Text `code` or `value`
Every wp-admin mention, URLs, variables, keywords, time, etc. should be written in
Don’t use these:
Text *italic* Text ***bold-italic***
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
Always use a descriptive alt. Images must be inside
images folder inside markdown file.
![Alternate text here](./fork_windows/fork.png "Alternate text here")