The vision is great
I fully agree with K-T’s silver lining that this exercise will make the Design Docs more useful for everyone. After the LDM-151 conversion exercise I heard from new DMers that they were pleasantly surprised at how useful and informative LDM-151 was. I do think using Docushare as both an official repository and the human-facing repo does them a disservice. By making these documents more readily, and pleasantly, available to DM and the public as beautiful websites we’ll have:
- a great resource for onboarding new team members,
- a great place to cross-reference in the other documentation (i.e., the software docs) for a global picture of how things are being built, and frankly
- if the documents are more visible, we as a team will be more apt to making sure these docs reflect our actual plans rather than being something that gets written, archived, and left behind in the heat of the battle
Having continuous deployment of the docs is also key to preventing Design Doc updates from being a massive chore.
Supporting reST & LaTeX for Continuous Deployment will cost Story Points
When I converted LDM-151 to reST, I could use Sphinx and readthedocs.org (RTD). RTD gives us continuous deployment of reST docs for free. If I only had to support reST, I could get on with just converting the existing docs with Pandoc and then spending some story points on extending the reST markup and fixing/re-designing RTD’s HTML/CSS/JS that seemed to be a bit buggy for the case of single-page deeply sectioned documents.
I feel bad for saying this, but the issue is supporting both reST+sphinx and LaTeX+tex4ht
simultaneously. If I have two formats, and two build tools, I can no longer use RTD. Instead, I have to build a ‘readthedocs for LSST DM Design Documents.’ Done properly, my JIRA stories would need to look like this:
- Build a web service that uses the uses the GitHub API to listen to their webhooks and build (via sphinx or tex4ht) & deploy webpages on commit.
- Extend reST to support extra syntax for Design Docs (via
sphinx kit
, so this story does have synergy with the Stack Docs).
- Implement tweaks to tex4ht workflows to support deep linking and inter-document cross referencing.
- Build HTML templates and CSS so that the reST and LaTeX documents ultimately have the same look and feel to a reader. Generally make a good reader experience.
- Perform content conversion of Word documents
Honestly, this plan looks like a lot of fun to me, but also keep in mind that I have only two weeks to implement this according to K-T’s schedule. Having only two weeks to sprint on this is nice because in principle it lets me get back to my normal work, but I fear:
- It won’t be perfect when it’s deployed September 25, and worst-case, bugs could become an impediment to everyone else’s productivity on this task. In an ideal world I’d have liked to make a Design Doc platform as a cool demo rather than a step in a live project that could set me up to become everyone’s blocker
- It will probably need to be continuously improved to some extent for the duration of the Design Doc update process this fall, costing additional story points
Ultimately how we do Design Docs isn’t my decision, but I hope that this post will elucidate what continuous deployment of the reST+LaTeX design docs means from my perspective.
So in an Agile sense, how about I sprint on this for two weeks and then we can decide what to do next?