Technical Notes (technotes) are a new platform for LSST DM staff to publish stand-alone documents that are native to the web. Technotes are written in reStructuredText, version controlled on GitHub, built with the same stack as DM’s next-generation software documentation, and made universally citeable with digital object identifiers (DOIs) provided through Zenodo.
I’ve written SQR-000: The LSST DM Technical Note Publishing Platform to provide an overview of the technote platform’s philosophy, role, and implementation.
You can start authoring technotes today with our lsst-technote-bootstrap project: https://github.com/lsst-sqre/lsst-technote-bootstrap
Some of the possible applications for technotes are:
- to report the results of a project, such as a data processing or software development experiment,
- to announce a new technology, serving as a high-level overview complementing software user documentation,
- to propose an architecture, possibly becoming the subject of a request for comment (RFC).
In many cases, you’ll find that Technotes are a replacement for writing on Confluence.
For more information:
- Read SQR-000 and take a look at its repository to see how it’s made
- Try making a technote with lsst-technote-bootstrap
- Learn more about writing in reStructuredText for DM
- Take a look at other technotes that have already been published
I welcome your questions and feedback about the technote platform in this topic thread. We intend to improve the production quality of technotes, ease the authoring workflow, and provide a useable index of DM docs. Above all, I look forward to reading your technotes.