For technical docs, I always advocate for documenting in source-controlled markdown. For all the same reasons we source-control our code. It's the bare minimum requirement for quality control of professional software work; no one would take a programmer seriously if they refused to put their code into source control and insisted on pasting code snippets around in a dozens of various tools and live-patching prod! Yet we do this with docs all the time. It's no surprise that we struggle with doc quality since its treated as second class to code.
If you want quality docs, we have obvious tools for that. Treat it like code. If you want to keep pasting random thoughts around and calling it "documentation", don't act surprised about the dismal state of your wikis.
Comments
For technical docs, I always advocate for documenting in source-controlled markdown. For all the same reasons we source-control our code. It's the bare minimum requirement for quality control of professional software work; no one would take a programmer seriously if they refused to put their code into source control and insisted on pasting code snippets around in a dozens of various tools and live-patching prod! Yet we do this with docs all the time. It's no surprise that we struggle with doc quality since its treated as second class to code.
If you want quality docs, we have obvious tools for that. Treat it like code. If you want to keep pasting random thoughts around and calling it "documentation", don't act surprised about the dismal state of your wikis.