Observatory Operations Style Guide

Important

The information provided below is based on the LSST DM reStructuredText style guide. A style guide specific to the procedure’s arm of the documentation will be provided at a later time.

The information below can help you create effective reStructuredText for the Rubin Observatory Operations Documentation.

Style and Voice

This is user documentation, which is different from academic writing. Here are some tips:

  • Make sure that all of your writing is in the service of users.
  • Write with the active voice and in the present tense as much as possible.
  • Address the user directly (“you can…”). Never use “we” since that’s ambiguous. If “we” means “Rubin Observatory,” then name “Rubin Observatory.” If “we” means the user, then say “you.” Even in tutorials, don’t use “we” to refer to an imaginary writer assisting the user.
  • Write simple, short sentences in short paragraphs. Chunk information with headers.
  • Write confidently and precisely, yet also casually.

File Names

Always use hyphens to separate words in directory and file names. Do not use underscores or spaces. This choice is based on the Google Developer Documentation Style Guide for search engine optimization.

Use start case for directory names unless it is appropriate otherwise (such as a common acronym like LSST).

Templates

A template folder is located in the project directory. It contains template pages for the Observatory Operations Documentation area, including a directory index and a procedure template. Review the README in the template folder for instructions, then update the contents accordingly.

Titles and Headings

Title case for headings is recommended.

Try not to use more than two levels of heading hierarchy. Using more than two levels of hierarchy might suggest an information architecture issue.

Also keep in mind DM’s reStructuredText heading styles.