Contributing to Observatory Operations Documentation

Below are instructions and guidelines on contributing to the Rubin Observatory Operations Documentation. This documentation is built with Sphinx and published to https://obs-ops.lsst.io.

This documentation is open source. Rubin Observatory welcomes contributions that make this documentation more useful and accurate.

Raising an Issue

If you spot an issue with the documentation, the best thing to do is raise a GitHub issue in the observatory-ops-docs repo. Include any relevant URLs with your issue description.

Creating a Pull Request

You can contribute directly to the observatory-ops-docs repo by creating a pull request. If you’re intending to make a substantial change, it’s a good idea to create a GitHub issue first with your proposal. Rubin Observatory can’t accept contributions that don’t fit with our strategy and roadmap.

These sections can help you create a successful pull request:

Building the Documentation Locally

These are the basic steps to clone and build the docs:

  1. Clone the GitHub repository:

    git clone https://github.com/lsst-ts/observatory-ops-docs
cd observatory-ops-docs

  2. Create a Python virtual environment (with venv, for example):

    python3 -m venv .venv
source .venv/bin/activate

    Note

    Activate this virtual environment in another shell by re-running the source command.

  3. Install the Python dependencies:

    python -m pip install --upgrade pip
python -m pip install -r requirements.txt

  4. You are now able to edit the cloned repository. The remaining items below are commands used to build and validate the documentation. These commands must be executed from the top-level directory.

  5. Build the site:

    make html

    Note

    Open _build/html/index.html in a browser to review it.

  6. Validate the documentation build:

    make linkcheck

    Note

    If some links are behind a login, you might need to ignore them. Look at the linkcheck_ignore variable in conf.py for examples of how to do this.

  7. Completely clear the build:

    make clean

Deployment

Whenever you push to the GitHub repository, the site is built for the corresponding branch. Find your build at https://obs-ops.lsst.io/v/. You can push to a branch you’ve created at any time.

The master branch is always published as https://obs-ops.lsst.io. Only authorized individuals can merge to master (may be delegated). To incorporate your suggestions, create a pull request.

Approval Process

  1. Verify the content with all authors and contributors.

  2. Create a PR.

  3. Request the following to review the PR:

    • Product Owner

  4. Respond to the comments received during the review process.

  5. After all reviewers approve, the submitter will squash commits and merge to master.

  6. Notify the PR was merged.

  7. Notify the authorized individual to tag the release.

Documentation Style Guide

New to reStructuredText and Sphinx

Check out these resources and guides. Sources files are available to compare raw reST and HTML outputs.

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 template directory. It contains template pages for the Observatory Operations Documentation area, including procedure, informative and troubleshooting templates.

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.