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 (
LDMdocuments, 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.
- 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.
- LSST Operations Technical Notes (OPSTN). This series if for technotes by LSST Operations. OPSTN technotes are hosted in the https://github.com/lsst-ops organization. Find OPSTN 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.
Create a technote¶
Creating a new technote is easy and takes just a moment. In Slack, open a direct message with @sqrbot-jr and type:
From the drop-down, select Documents > Technote (reStructuredText) or (LaTeX) depending on the format you wish to work in. 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, including a link to a pull request.
You need to merge the bot’s pull request in order for your technote to appear on the web.
Once the initial configuration pull request is merged, any time you push to GitHub your technote will be republished at its
Pushes to the
master 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 LaTeX-formatted technotes¶
LaTeX-formatted technotes use the
The lsst-texmf documentation explains how to write
Working with reStructuredText-formatted technotes¶
See the ReStructuredText Style Guide for a primer on writing reStructuredText. The sections below deal with specific issues for technote projects.
Using bibliographies in reStructuredText technotes¶
The lsst-texmf project includes shared BibTeX bibliographic databases. You can also use these bibliographies from reStructuredText technotes.
First, add or uncomment the
bibliography directive at the bottom of your technote’s
.. bibliography:: local.bib lsstbib/books.bib lsstbib/lsst.bib lsstbib/lsst-dm.bib lsstbib/refs.bib lsstbib/refs_ads.bib :style: lsst_aa
Only include the
local.bib file if your technote’s repository has one.
local.bib to temporarily store bib items before you permanently transfer them to the lsst-texmf project.
The bibliographies in the
lsstbib directory are copies from the https://github.com/lsst/lsst-texmf repository.
Refresh the copies maintained in your technote’s repository by running this command:
To make citations in the technote’s text, use the
In-text citations are numbered, not author-year style.
Editing metadata in reStructuredText technotes¶
ReStructuredText-format technotes use a
metadata.yaml in their repositories to describe attributes like the document’s title, author list, and abstract.
To change the technote’s title or author list, for example, commit a change to the
See the comments in
metadata.yaml for a description of these fields.