When working on the documentation, you should follow this style guide to ensure a consistent tone, formatting, and context throughout Medusa’s documentation.
This guide will help you understand how to approach writing a documentation page and what rules you should follow when writing.
<aside> 💡 We use Vale to enforce these style guides in the documentation. It’s used for validation in PRs and using the Vale VS Code extension. You can learn more here.
</aside>
Documentation is written for developers who want to learn more about how they can set up, use, and customize Medusa. So, the content of the documentation should be straightforward.
Each documentation page should focus on its topic. Focus on the technical details that would be important to developers.
Make sure to include any relevant detail. If the documentation page is a how-to guide that explains to the developer how to do something, then it should include every step that allows the developer to get the job done.
If the page is a conceptual guide, then make sure that it includes all the details necessary for the developer to properly understand the concept at hand.
All documentation details must be correct. If you’re unsure about a certain detail, you should check with the relevant team member for confirmation on whether it's correct.
The documentation will ultimately be published in Markdown format. So, you should either write in Markdown or use tools that allow you to export the content in Markdown. It’s recommended to use a Notion document under the ‣ as it has templates that will guide your writing.
Throughout the documentation, you should refrain from using first-person pronouns (I, we, us, etc...). You should always talk to the developer directly.
When you abbreviate certain terms, you should write the full term the first time you mention it, then use the abbreviation later on.
For example, Start by installing Create React App (CRA).
However, if these terms are widely known as the abbreviated version, then there’s no need to mention the full term. An example of that would be HTML or CSS.