Contributing to the docs

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

Keep in mind that everyone participating in this project is expected to follow the LSST DM Team Culture and Conduct Standards.

Raising an issue

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

If you need help with the Notebook Aspect, in general, reach out on one of our support channels first.

Creating a pull request

You can contribute directly to the nb_lsst_io 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. LSST 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 docs locally

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

git clone https://github.com/lsst-dm/nb_lsst_io
cd nb_lsst_io

Next, create a Python virtual environment (with venv, for example).

Once you’ve done that, install the Python dependencies:

pip install -r requirements.txt

Finally, run these commands to build and validate the documentation:

make html
make linkcheck

To force a complete rebuild of the documentation, you can clean-up the existing build:

make clean

Documentation style guide

This documentation is written in reStructuredText. The LSST DM reStructuredText style guide can help you create effective reStructuredText.

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 “LSST,” then name “LSST.” 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 simply, with short sentences and short paragraphs. Chunk information with headers.
  • Write confidently and precisely, yet also casually. Contractions are good.

For further discussion about specific style issues, refer to the Google Developer Documentation Style Guide.

File names

Always use hyphens to separate words in file names. Don’t use underscores or spaces.

Prose formatting in plain text

LSST DM’s user documentation is written with soft wrapping, meaning that lines are as long as they need to be in the plain text file and the text editor is expected to handle wrapping. Never hard wrap to an arbitrary line length. Soft wrapping makes editing more approachable for more people (particularly those using the GitHub editor) and makes pull request line comments more useful.

More specifically, use semantic line formatting. Generally this means that each sentence should be its own line in the text file.

Titles and headings

Use sentence case for headings (don’t use title case). Capitalize proper nouns as usual.

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.