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.
Tone and Content¶
This is user documentation, which differs from academic writing.
Make sure that all of your writing is in the service of users.
Keep it friendly and conversational, and write confidently and precisely.
Write simple, short sentences in short paragraphs.
Do not use please and thank you.
Avoid “simply” ,”It’s that simple”, “It’s easy”, or “quickly” in a procedure.
Language and Grammar¶
Write in second person and use you instead of we.
Use Present tense. Avoid the use of would and other conditional forms.
Write in the active voice to make instructions clear and direct.
Active Voice
The subject of the sentence is the person or thing performing the action
Recommended: Send the command to the server. The server will respond in 1 min
Not recommended: The server is commanded and a response is received
Follow standard American spelling and punctuation rules as defined by Merriam-Webster.
Formatting, Punctuation, and Organization¶
Organize your document using sections and subsections.
Avoid parentheses; use commas or dashes instead when adding information.
Use numbered lists to present steps that must be completed in order.
Use bulleted lists for general lists that do not follow a sequence.
Section Headings and Document Titles¶
Create descriptive headings and titles to facilitate navigation.
Limit heading hierarchy to no more than two levels if possible.
Use Title Case for headings and titles.
Title Case for Headings and Document Titles
Capitalize the first and last words, as well as all other main words.
Keep minor words, such as articles, coordinating conjunctions, and prepositions, in lowercase.
Examples: Science Fiction Classics: Exploring the Timeless Stories of Distant Galaxies or The Mystery of the Missing Shining Diamond
Filenames and Directory Names¶
Use hyphens to separate words in directory and file names.
Do not use underscores or spaces, as hyphens improve search engine optimization.
Apply Start Case for directory names
Start Case for Files and Directories
Capitalize the first letter of each and every word.
Separate words with hyphens.
Examples: AuxTel-Weather-Constraints or LSSTCam-Troubleshooting
Links¶
Do not use use “here” as link text. Instead, make the relevant noun or phrase the link.
Templates¶
A template folder is located in the template directory. It contains template pages for the Observatory Operations Documentation area, including procedure, informative and troubleshooting templates.