Recently on Slack we talked about lsstsw and where it should be documented. There’s some practical documentation on lsstsw as an installer in pipelines.lsst.io, and there’s also documentation carried over from confluence in developer.lsst.io.
My proposal is to create a new documentation project specifically for the lsstsw product, which will have the domain
Reasons for a standalone documentation project are:
pipelines.lsst.io [will] be primarily built from documentation in Stack packages, and lsstsw doesn’t fit that model. lsstsw is really a CI tool that happens to be a useful developer tool as well.
- Qserv is also a user of lsstsw; putting lsstsw in pipelines.lsst.io is confusing.
developer.lsst.io is sort of a wiki-in-the-documentation-engineering-era, where we put developer policies/playbooks/information that isn’t associated with a code base, but is associated with the DM team. In other words, a code product shouldn’t be documented in the DM Developer Guide.
- By putting lsstsw’s documentation in the lsst/lsstsw GitHub repo and continuously publishing it to
lsstsw.lsst.io we take advantage of the docs-like-code methodology. As lsstsw evolves, the documentation evolves with it. I’m doing this with LSST the Doc’s components/microservices (ltd-keeper.lsst.io, ltd-mason.lsst.io, ltd-conveyor.lsst.io) and it really is a fantastic workflow.
To mitigate having an extra documentation microsite we will:
- Link from the pipelines.lsst.io installation page to
lsstsw.lsst.io. Note that with EUPS binaries coming in the future, we’ll have fewer reasons for most developers and users to use lsstsw.
- Have a landing page for lsstsw in the DM Developer Guide’s Build/CI section to explain what lsstsw is and what it can be used for, and then link to
lsstsw.lsst.io for in-depth documentation.
- Link to this project from the up-coming
www.lsst.io documentation hub, along with all our other projects/products and documents.
I intend to do this today at the JTM Hack Session. I think it’s in my purview to make this decision, and I think it’s non-controversial, so I haven’t (yet) made an RFC for this. However, if a stakeholder thinks otherwise I can hold off.