Writing Guide

Standard Requirements

Document every feature

The most important part of docs is to provide the information that the user needs. If a feature is missing from the docs, it’s as if it doesn’t exist. With Alokai, not only is there a lot of information to cover, but it’s also constantly changing. It’s important to keep the docs up to date.

Additionally, there are times when there will be domain-specific knowledge outside of Alokai that my help a user understand something better. In these cases, it’s important to link to the relevant information.

Avoid complex language.

Using terms that a reader isn't familiar with can make the docs harder to follow. Avoid jargon, abbreviations, and acronyms unless they are explicitly explained in the docs. Consider creating a glossary of terms and linking the first occurrence.

DX Specific Guidelines

The Step-by-Step test

When writing Docs, try and take a step back and visualize trying to use the doc to complete a task, or even better, try and follow the doc step-by-step and see if you’re able to complete the task.

Brevity is good, but clarity is great

Ideally, our docs should enable a developer new to Alokai to get the necessary knowledge to complete their tasks. When in doubt, over-explain. Devs will naturally skip what they don’t find interesting. But those who need the information will be happy it’s there.

Make the Developer’s life easy

Bonus points if they can complete the relevant task by only copying and pasting.

Target Audience

Assume a junior-level programmer with no Alokai experience when writing the docs.

Organization

If you're building an official integration and would like your docs featured on the Alokai website, your docs folder should only contain content files (.md, .json, .csv, and .yml or.yaml files) and static assets.

This will allow your docs to be loaded as a Nuxt Content GitHub source.

/getting-started
    index.md
    introduction.md
    installation.md
  my-image.png
/guides
    category-1/
        overview.md
        usage.md
    category-2/
        more-pages.md

Besides “Home” (which is a link to / ) - each of these sections should get a dedicated folder in the docs.
Consider naming files index.md for cleaner routes.

Writing Guide

Provide context on each page that tells someone why/when they would use this information.
Headings should be simple and describe the features a user will implement (e.g. “querying products”, “filtering products”, “SSR cache”)
Describe the problem first, then the solution. Before showing how a feature works, it's important to explain why it exists. Otherwise, users won't have the context to know if this information is important to them (is it a problem they experience?) or what prior knowledge/experience to connect it to.
- Avoid docs where we are only telling a developer what to do without any explanation of how each step fits into the bigger picture of what they’re trying to solve
When you assume knowledge, declare it at the beginning and link to resources for less common knowledge that you're expecting.
Acknowledge any prerequisites at the top of the page. If there are any other guides that have to be completed already, call them out here.
Include expected output/screenshots during complicated steps.
Respect users' cognitive capacity.
- Cognitive capacity is depleted faster by complex sentences, having to learn more than one concept at a time, and abstract examples that don't directly relate to a user's work.
- Cognitive capacity is depleted more slowly when we help them feel consistently smart, powerful, and curious. Breaking things down into digestible pieces and minding the flow of the document can help keep them in this state
Always try to see from the user's perspective - When we understand something thoroughly, it becomes obvious to us. This is called the curse of knowledge. In order to write good documentation, try to remember what you first needed to know when learning this concept. What jargon did you need to learn? What did you misunderstand? What took a long time to really grasp? Good documentation meets users where they are.
Show, don’t tell.
Add comments to code samples.

Language and Grammar

Use plain, correct, and friendly English.
Prefer simpler words and phrases.
Use the Oxford comma.
Avoid language that invalidate struggle.
When referencing the name of a project, use the name that project refers to itself as.
Use contractions to make your writing friendlier.

Writing Resources

Adapted for Alokai from the Vue Docs Writing Guide.