Documenting lsstsw as a standalone software product (proposal)

Data Management
#1

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 lsstsw.lsst.io.

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.

3 Likes
#2

As long as this is easy, I have no objection (certainly not for hack session work).

My only concern is that lsstsw is really not an ideal developer tool, and I wonder it’d be better to hack up a similar tool (probably starting from lsstsw; certainly using lsst_build) that is geared towards developers before investing much documentation effort into lsstsw.

#3

I completely agree with the premise of a better developer-facing build tool—we could RFD that.

That said, I don’t see lsstsw going away from a CI perspective for a while, and it’s still useful for SQuaRE to document our tools (it’s been a knock on us that a lot of CI and build infrastructure is under documented). So I don’t think this is a waste of our time (and it’s not that much time :slight_smile: )

Is scons used by lsstsw to install third-party lightly-warpped packages?