Writing Style Guidelines

Here at Introspective Systems, we work hard to maintain a creative and welcoming community. We do this by making sure we follow some basic writing style guidelines when writing xGraph documentation. You should follow these guidelines when writing xGraph Module documentation.

  1. Write concisely and clearly. Only use technical jargon where it is appropriate. When writing user documentation, remember that the reader may have little or no programming experience.

  2. Don’t use ambiguous pronouns. Use a noun when there is any chance of contextual confusion.

  3. Use gender neutral they/them when talking about the user or reader. This is an easy way to maintain an inclusive community, and takes the difficulty out of trying to figure out the documents voice.

  4. Do not use any language that demeans or degrades a person or a group of people. We want this to be an inclusive community, so keep political and social opinions out of writing.

  5. Use active voice. Using the active voice means that the subject of the sentence is the person or thing that carries out the action expressed by the verb. Consider the following:
    • The enter key is pressed by the user. (Passive voice, avoid this!)
    • The user presses the enter key. (Active voice, strive for this!)
  6. Use the code block syntax when referring to code. Adding examples to documentation is always encouraged. For readability, make sure you use the Markdown code block format for all code references in your documentation.