3 ms·
Somewhat OT, but maybe related. Does anyone actually work as a QA for documentation? I've been in many projects where "just read the docs" or "go read this do
by mgkimsal 11y ago
Somewhat OT, but maybe related.
Does anyone actually work as a QA for documentation? I've been in many projects where "just read the docs" or "go read this doc", and... nearly always it's out of date, or missing key information (like who wrote it, who to contact for access to systems in the document, etc) or so scantily written as to be useless.
Saying "I wrote docs" but having them be abysmal seems to be the norm. People now accept that having unit tests for code is a thing (not always done, but at least a thing) - is there an equivalent for documentation?
- vehementi 11y agoSome companies have a dedicated technical doc team for this purpose yeah.
- yarou 11y agoI'm surprised literate programming[0] never really caught on. Rather than have separate documentation, the paradigm is completely different. Source code generation is interspersed with the abstract flow of thoughts that one usually has while developing. This style of coding seems to be natural to me, as many algorithms are a set of discrete steps in an abstract sense. Implementing concrete steps and then describing their abstract counterparts seems sort of backwards to me. [0] https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming