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.

Writing Style

🗣 Tone

Documentation is written for developers who want to learn more about how they can setup, 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 tutorial that guides the developer to do something, then it should include every step that allows the developer to get the job done.

If the page is more of an overview, then make sure that it includes all the details necessary for the developer to properly understand the topic.

☑️ Facts

All documentation details must be correct. If you’re unsure about a certain detail, you should check other existing documentation or blog posts and see if they hold answers to your questions.

If you can’t find the clarification you need, you should ask the technical team for help. You can send your questions or get on a call with them.

Document Format

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. You can use tools like Notion, Dropbox Paper, or any other tool that allows you to export in Markdown.

Word Choice

👉🏻 Use “you” as the Main Pronoun

Throughout the documentation, you should refrain from using first-person pronouns (I, we, us, etc...). You should always talk to the developer directly.

🆎 Abbreviated Terms

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.