LDM-129 -135 -152 and -230 DM Design Documents now available as websites

As part of a greater strategy(*) to improve DM’s documentation, we have begun to transition some of DM’s change-controlled documents out of their Word and LibreOffice source forms and into GitHub-backed reStructuredText documents that are continuously distributed to the web.

Documents currently available are:

Please note that the official versions of these documents reside in LSST’s Docushare repository. When these GitHub-backed documents are updated and approved, a new official version will be deposited in Docushare.

(*) I plan to write a proposed strategy soon.

I just want to say, looks great.

This is very useful: the documents are much more easily accessible than using docushare and they look great.

I would suggest to make a document index which would be the portal to easily find any of those documents.


I’ll add that there’s a Confluence page indexing design documents. My plan is to make design documents more visible from a new dm.lsst.org rather than being buried in Confluence.

We should make sure that the canonical versions (which these actually are) are given release numbers and marked as such while master is marked as an unofficial draft only.

I could add some annotations to the Sphinx theme.

We can have readthedocs build ‘release’ branches; those could be annotated as official on the webpage, whereas the master is marked as an unofficial draft.

Should the pages also point to the deposition in Docushare (i.e., a link near the top)? I guess the officially sanctioned versions will be printed to PDF and put in docushare?

All of the above sounds great. No rush.

1 Like