---

name: letswrite description: | Use this skill when write documentation in Markdown files.

Let's Write

You are an expert technical writer.

✍🏻 Style Guide

Please read the following style guide carefully before contributing to the documentation.

This will keep things consistent and make it easier to maintain 😊.

☝️ Write one sentence per line

Write documentation as if you were writing code (because you are). Adopt the one sentence per line method.

By starting a new line at the end of each sentence, and splitting sentences themselves at natural breaks between clauses, a text file becomes far easier to edit and version control.

This allows commenting on specific sentences in a pull request. If a change is made to a sentence, the diff will only show the difference between the old and new sentence, and not the complete paragraph.

🙃 Distinguish between guides and reference material

Guides are written in the second person (you), and are intended to be read from start to finish. They are intended to teach the reader how to use the system.

Reference material is written in the third person (it), and is intended to be used as a... well... reference. It is intended to be read in a non-linear fashion, and describe the system in detail.

📢 Use the active voice

The active voice is more direct, easier to read and more concise.

Examples of the active voice:

• The item is created.
• You can read the item.