Technotes for Stand-Alone Technical Documentation

Technotes are a way for Data Management team members to write standalone documents that are native to the web, can be cited in literature, and are easy to write, publish, and update. You can write with either our reStructuredText or LaTeX templates. All technotes are developed on GitHub and published with LSST the Docs. You can find a listing of available technotes at www.lsst.io.

When to write technotes

Some of the possible applications for technotes are:

• Report the results of a project, such as a data processing or software development experiment.

• Announce a new technology, serving as a high-level overview complementing user documentation.

• Propose an architecture, possibly becoming the subject of a request for comment (RFC).

For further background, see SQR-000: The LSST DM Technical Note Publishing Platform.

Technotes are not always the right platform for your information. Consider these alternatives:

• Change-controlled documentation (LDM documents, for example). See LPM-19 for guidelines on what kinds of information are change-controlled.

• User documentation (https://pipelines.lsst.io, for example). Descriptions of how to use software, services, or data should be written as user documentation. Technotes complement user documentation by being point-in-time discussions of software, like a technical blog post.

Technote series

• Data Management Technical Notes (DMTN). This is the general purpose technote series for the DM team. DMTN technotes are hosted in the https://github.com/lsst-dm organization. Find DMTN technotes.

• Rubin Technical Notes (RTN). The RTN series is for technotes relating to Operations that cut across individual systems, or relate to functions that cut across departments such as management, planning and operational procedures. RTN technotes are hosted in the https://github.com/lsst organization. Find RTN technotes.

• Project Science Team Technical Notes (PSTN). This series is for technotes by the LSST PST. PSTN technotes are hosted in the https://github.com/lsst-pst organization. Find PSTN technotes.

• Systems Integration, Test and Commissioning Technical Notes (SITCOMTN). This series is for technotes by the System Integration, Test and Commissioning Team. SITCOMTN technotes are hosted in the https://github.com/lsst-sitcom organization. Find SITCOMTN technotes.

• SQuaRE Technical Notes (SQR). This series is for technotes about SQuaRE products and services. SQR technotes are hosted in the https://github.com/lsst-sqre organization. Find SQR technotes.

• Simulations Technical Notes (SMTN) This series is for technotes by the LSST Simulations team. SMTN technotes are hosted in the https://github.com/lsst-sims organization. Find SMTN technotes.

Operations vs construction

The DMTN and SQR series still exist in operations and so it may still be used. In general if a topic fits in a given series use the series without hesitation.

Create a technote

Creating a new technote is easy and takes just a moment. In the rubin-obs Slack, send a message to Squarebot:

/msg @Squarebot create project

From the drop-down, select Documents > Technote <format> for the format you wish to work in:

• Documents > Technote (reStructuredText) creates web-native technotes using the same reStructuredText markup as Python docstrings and most Sphinx documentation

• Documents > Technote (Markdown) use the same HTML output as above, but with Markdown syntax

• Documents > Technote (lsstdoc LaTeX) is the LaTeX format for Rubin documents (PDF output)

• Documents > Technote (AASTeX LaTeX) for AAS preprints (PDF output)

• Documents > Technote (ADASS LaTeX) for ADASS conference proceedings (PDF output)

• Documents > Technote (ASCOM LaTeX) for Astronomy & Computing preprints (PDF output)

• Documents > Technote (SPIE LaTeX) for SPIE conference proceedings (PDF output)

Once you select the template type and fill in the form on Slack, the bot will create and configure the technote on GitHub. Watch for Slack messages from the bot about the technote’s GitHub repository and publication URL.

Tip

The template form asks for your author ID. You can find your author ID in the Author DB Google Sheet. Send a pull request to update your entry in authordb.yaml, or use the Google form linked from the #all-users channel in Slack.

Updating a technote

Any time you push to GitHub, your technote will be republished at its lsst.io site. Pushes to the main branch update your technote’s main page, while updates to other branches update preview editions behind the /v/ URL path. Click on the Switch editions or Change version link from your published technote to get links for other editions.

Working with reStructuredText or Markdown technotes

See the Documenteer technote documentation for information on writing and building reStructuredText or Markdown technotes.

Working with LaTeX-formatted technotes

The lsst-texmf documentation explains how to write lsstdoc-based documents.