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

Data Management DM Notifications
#1

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.

#2

I just want to say, looks great.

#3

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.

#4

:thumbsup:

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.

#5

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.

#6

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?

#7

All of the above sounds great. No rush.

1 Like