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 break 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

Product

Engineering

Last modified 3mo ago

Export as PDF

Copy link