@tedu mentions how Brooks sketches out the idea of this extensive documentation and production bible as being essential to large projects. At the time he was writing this, he mentions that lots of secretaries and typists were employed to keep these up-to-date every evening while the engineers had gone home (if memory serves).
I’m still surprised to this day that this lesson hasn’t been taken to heart, and that more organizations rely on things as clumsy as code comments to provide a poorer service. At every engineering team I’ve been a part of one of the first things I do is push for a wiki or even mailing list to store design and architectural decisions.
It’s amazing to me that our tooling has outstripped our practices here.
Secretaries and typists cost money which we could be spending on the big data cluster we need to crunch these 100mb csvs
They still do this in high-assurance since the regs force it. For instance, both Orange Book and DO-178B required requirements, high-level design, at least one low-level, code, tests, and important proof they all fit together with correspondence (i.e. traceability). Any code better trace back to a design decision that better trace back to a requirement. Every requirement or design element that can have a test better have one.
Im not sure what tools most use for this outside vendor-specific ones. Some developed Topcased in Eclipse for it. I know Karger et al on Caernarvon project used Framemaker for its cross-linking capability. You could just jump from one artifact to another with each module having a summary page. Final result could be exported as HTML or something like Common LISP hyperspec.
Something wrong with the site? It says connection insecure for me (Invalid certificate).
No, site works fine. It’s just that our browsers are defective.