Technical Writing
Rocket.Chat Documentation Guidelines
If you are a new Technical Writer joining our team or a community member who wants to contribute to Rocket.Chat documentation, here are some actionable writing guidelines you can apply to make your writing in tune with our documentation. They may seem painfully simple and obvious, yet if you ignore them repeatedly in your piece, the document might lose its tone/purpose.
- Try starting actionable instruction with a verb. (e.g., “Click Submit…” [Correct] vs. “Please click the Submit button…” [Not Preferred])
- Use the actual names of UI components only, not their types. (e.g., “Click Submit…” [Correct] vs. “Please click the Submit button…” [Not Preferred] OR "Turn Enable encryption on" [Correct] vs. "Turn on the Enable encryption toggle" [Not Preferred])
- Use Active Voice whenever possible (e.g., “You can change these configurations by…” [Active] vs. “These configurations can be changed by…” [Passive])
- Use simple, short sentences.
- Use screenshots wherever necessary.
- Mark your screenshots always, as shown below:
- When documenting a new topic in a feature, always use branches and dedicated pages. This way, the necessary information is searchable by users through keywords on the page title, as shown below:
- Use headings, bullet points, and links to breaking up information into chunks, not long explanatory paragraphs
- Actionable items in a bulleted list should not end in a full stop
- Use tables and diagrams, not sentences, to represent information with multiple dimensions
- Always spell check for typos and grammar check for polish
Last modified 5d ago
Export as PDF
Copy link