Announcing the DM Technical Note Series

Data Management DM Notifications
#1

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:

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.

2 Likes
Listing of available DM Technotes
#2

@jsick Do you know if we have a Project technote series, for non-DM stuff?

#3

Sims has a technote series (see Listing of available Sims Technotes) that uses the DM tech note system. it’s not a project-wide standard though.

#4

Ah, that’s a real shame, it’s a nice system and would be great if the project adopted it. Who do you think I should say that to, if not you. @drphilmarshall, were you looking into doing this?

#5

If SQuaRE feel they can handle it, then there is no reason why other parts of LSST can’t request a tech note-style document series.

#6

@merlin Yes, we’re certainly happy to have other LSST groups participate in the DM documentation platforms like technotes and lsst.io. We’re trying our best to build platforms that scale without extra effort.

I spoke with @drphilmarshall at LSST 2016 and it looks like there’s definite opportunity to have technotes for science collaborations (probably with some modifications requested by the science collaborations).

Related, I’ve been working on writing down a high-level strategy for DM documentation: LDM-493: Data Management Documentation Architecture. Be aware that the link is to a pre-change control draft, so things can change. (Also, excuse any temporary cert errors. I’m getting that fixed). In general, anything you see in LDM-493 can work equally well for LSST groups besides DM.