User documentation style guide

This style guide will help you write technical end-user documentation content for LSST Data Management.

The style guides

Our core style is described by the Google Developer Style Guide, plus a list of customizations.

If the Google Developer Style Guide doesn’t address your situation, you can fall back to these resources:

Where to use this style guide

This style guide is for LSST’s end-user documentation. A user is anyone that uses the software and services we build for LSST. Users can be astronomers in the community, future operators of LSST, and even your fellow developers.

More specifically, refer to this style guide when writing any content that services a user:

  • Documentation content (guides, tutorials, how-tos, and references) for software and services.

  • Content for LSST websites.

  • “Docstrings” in code that are used as API references.

  • Copy printed to the console (like error messages).

  • User interface microcopy.

There are common contexts where this style guide does not apply:

  • Project documentation (such as policy, requirements, design, test documents, and technical notes).

  • Academic manuscripts (such as papers and conference proceedings).

In those contexts, use the Project Publications Style Guide or the journal’s style guide.

How to use this style guide

In LSST DM, we are all responsible for contributing to the documentation for the things we create. At the same time, writing technical documentation for users differs in many ways from other types of writing we might have more experience in (such as academic writing). Given that, treat this style guide as an educational resource. As you learn more from this style guide, your technical writing will improve, and LSST’s documentation as a whole will become better and more consistent.

It’s not realistic to expect you to internalize every facet of this style guide immediately. Instead, begin by reviewing the Highlights. As you write content and have questions, refer to the style guide for solutions to your particular writing problems. Reviewers in a pull request might point out style issues. If it’s realistic in the time available, try to update your content to fit the recommended style. In any case, be open to learning so that the next batch of content you create will be even better.

See the About this guide page from the Google Developer Style Guide for additional thoughts, including when to break the rules.