Requesting Comments for Design Documentation Format for DM

I respect your right to veto this, but I don’t want an open ended “let’s revisit” line. It’s not helpful for planning because it is not clear how the relative pros and cons will have changed or how we would measure those changes.

So, the ruling is, no Sphinx/RTD for DPDD and LDM-151.

@jsick don’t cry, you can do the SQuaRE Design Document :slight_smile:

I think LaTeX is the right decision here too (and I take no offence; it was actually a very valuable story point for me from a doc perspective).

One thing I would encourage us to do as an add-on is to compile the LaTeX source into HTML (as @timj suggested; and while we’re at it, compile to PDF) via continuous integration. Having an HTML rendering of these documents is important for discoverability and also for integration into the online DM documentation sphere (docosphere?) that I’m building.

1 Like

I assume we all compile to pdf by default. Should we be using pdflatex or xelatex?

The worst problem I have had with the corpus of documents comes from my experience bringing on new people at NCSA. People cannot pick up a design document and understand 1) what is invented by the author of the document v.s 2) what in the document is reflective of requirements or other constraints in governing doc sets.

Or in a phrase, there is no traceability.

I am working on making changes to LDM-230 so we can make a reviewable earned value plan for the L1 system. I’m currently working in Confluence so I can take the input of others and be in an environment where linking is possible, and might be of use implementing traceability.

I really think this is a first-class problem in the project, and I’s hope it could be addressed.

Having html rendering would be really useful. Whenever I have used this, I find latex2html renderings tend to be linked and hierarchical (ie. a page with sections each of which link to the stuff in the section) which is less useful than the typical readthedocs rendering (for example the one you made).

Is there an option in latex2html (something like single page html?, though it would still not have the sidebar), or perhaps a different program that would render it in a more useful way for this context?

Given a choice, I’d say that tex4ht is significantly better than latex2html. Recently I was involved in a project to switch the Starlink documentation (hundreds of latex documents) over from latex2html and the results were significantly improved in rendering and time to generate the docs. Some customization code is required to handle project-specific class files and the like.