Style guide#

We generally follow the Microsoft Manual of Style (MSTP) in our documentation. This topic summarizes some of the most notable rules in MSTP, and notes where we have selected to diverge from their guidance.

Microsoft Manual of Style (MSTP)#

MSTP is huge, so a few of the most notable rules to be aware of are listed below.

  • Use the Oxford comma (serial comma).

  • Don’t use “should”–it’s ambiguous. Rather, say a user must do something or that a computer/system will do something.

  • Verb tense and voice

    • In general, use present tense and active voice.

    • Use primarily second-person (you).

    • Use first-person (I or we) sparingly. For example, “We recommend…” is more natural than “It is recommended that.”

  • Be direct and use simple sentence structure.

    • Avoid jargon

    • Don’t use i.e. or e.g. as they can cause problems for non-native English speakers or machine translation.

Procedures#

Procedure guidelines are extensive (see chapter 6.) The primary points to follow are:

  • Sentences must provide the context and then the action. For example, “In the Print dialog box, click All.”

  • Each step must encompass a single action, unless they are short and occur in the same place.

  • Additionally, you “click”, you don’t “click on.”

  • Generally avoid using “please” and “thank you.”

  • Use imperative mood. In other words, verbs should take the form of commands. For example, “Enter your password” not “The user enters their password.”

  • Consecutive list items should be separated by > and not ,. For example, “Select Explore > Experiments”.

Differences from MSTP#

Our house style guide differs from MSTP guidance in the following ways.

Parameters#

  • Use bold, not italics, for parameter names.

  • Parameter values, which are often in all-caps, are in plain text.

Placeholder text#

  • Surround placeholder text with angle brackets.

  • For example, text where users are expected to enter their username C:/Users/<username>.

  • Include a reusable snippet about what this indicates where used.

JSON examples#

  • Use 4-space indentation in JSON examples.

  • Here’s a handy way to convert space indentation in Sublime.

  • Sphinx will produce errors if the JSON syntax is incorrect (https://jsonlint.com/ is a great resource).

  • Place JSON files in the json directory and pull into content using the literalinclude directive.

    • This allows us to easily test our JSON examples in the future.

    • Also makes it easier to reuse examples.

  • For JSON examples within the parameter tables, use the code-block directive.

Titles and headings#

  • Use sentence case for topic titles and headings (same as MSTP).

  • For procedural content, MSTP generally recommends imperative mood but says there’s a lot of variation across groups. We are using “how to” for the top-level section and imperative mode for all others. For example, “Run a simulation” not “Running a simulation” or “How to run a simulation.”

Species names#

  • Italicize species names. For example, A. funestus and A. gambiae.

  • A note on mosquito names: for scientific naming convention, the first time you mention a species you give its full name (Anopheles funestus), and then the second time you can abbreviate the genus (A. funestus). However, there are two “A” mosquito genera that are commonly discussed in the disease literature (Aedes and Anopheles), so it’s convention to use the first two letters of the genus name when abbreviating: An. funestus and Ae. aegypti. For pretty much every other category of organism, you’ll just use the first letter and not the first two.