4 ms·
For real. On Palladium/NGSCB there was a strong effort to maintain correspondence between documentation and code, to the point that there was an effort to have
by pacaro 9y ago
For real. On Palladium/NGSCB there was a strong effort to maintain correspondence between documentation and code, to the point that there was an effort to have header files be generated directly from the specs, which were Word docs. The biggest practical challenge was that the extractor had to instantiate Word just to read the text content of paragraphs with the specified style. This is not something that you want in your build pipeline if you can avoid it.
- wglb 9y agoEwwww. I woulda cobbled something together to suck the text out of them.
- pacaro 9y agoHahaha, me too, but the old Word format really is as bad as everyone says, and we were trying to build a system with formal correspondence from spec to code (and sometimes from spec to proof to code), so having a "cobbled" together something really didn't fit the model. The real problem was using word as our documentation format, but at Microsoft in the early oughts there really weren't many alternatives.
- wglb 9y agoWell, I do believe LaTeX was available. The cobble-together part, to be successful, would pull the text out reliably. And the format is readily documented, and Open/Libre office processes it as well. The code to do the extract might be ugly, but so long as it reliably produced the text in a CI/CD environment, that would be OK.
- pacaro 9y agoThe constraints were entirely organizational, many better technical solutions were suggested