Documentation Style Guide

The style guide is designed for both the documentation contributors and linguistic editors. The style guide should be enforced across the board for the sake of content quality, consistency, and readability.

Beforehand

• Make sure you understand your audience first. Your content is exposed to audiences with various technical backgrounds and skill sets. Ensure that your work is accessible to both new and experienced readers.
• Carefully choose your topic. Your content should be structured circling this topic.
• Ensure you have understood the type of your content. For example, is your content a step-by-step tutorial, a technical overview, or an essay for the general public?
• Determine the scope and prerequisites for your content.
• Adopt a fitting style guide.

General writing tone and style

• We encourage the writers to use Plain English and help the readers grasp the content easily. It could be helpful to keep your content clear and concise.
• Make sure your paragraphs are structured for a unified topic. Your sentences should be short, grammatically robust, and linguistically consistent.
• We promote using inclusive wording as the universal style of expression.

Language and grammar

• American English is generally preferred.
• For a new term, spell out the word followed by its abbreviation. For common abbreviations such as RESTful API and HTML, there is no need to specify.
• The tone of your writing should match the topic and purpose. When you want to create a more personal tone, use the second person.
• Active voice is preferable to passive voice when possible.
• Use present tense to write your draft.
• Pay special attention to your grammar, which includes:
  • American English spelling. For example, use "center" instead of "centre".
  • Definite and indefinite articles. You can exclude these articles from titles and headings.
  • Correct capitalization. Use the sentence case for titles and headings.
  • Pronouns should have clear indications. For example, "It is the best exploratory data analysis tool" does not indicate who "it" is. To avoid vagueness and confusion, rewrite the sentence as "RATH is the best exploratory data analysis tool".
  • Ensure your punctuation is correct according to the common guideline.

Edit your content

Now that you have a draft, you're halfway through the process. Make sure you have completed the following linguistic editing steps before submitting your content.

• Read it again. As the best practice, find a peer reviewer to give you feedback.
• While reading, consider the following issues:
  • Is your content easily understandable to your audience?
  • Is your content well-structured?
  • Does it contain examples that make the reader easier to digest?
  • Is the technical information correct?
  • Is there any sensitive information that you do not want to disclose?
  • Most importantly, what does your audience learn from your content?

Submit your content

RATH Doc Center uses Docusaurus as its content management platform.

You can use Markdown, a markup language popular with many technical writers and programmers, to create and edit documents.

Contact us to have a submission workflow being set up for you.