I’m usually on the documenting side of things. If something like this starts unfolding, I produce text or HTML files anyway, they go on github/lab/whatever, and I wash my hands of what happens next.
In the end I write documentation mostly for myself. When the company can’t figure things out over Discord or whatever ephemeral chat interface they use, I get called anyway.
I do extensive in-code documentation. The compiler discards all comments so I don’t worry about commenting my code. Source code is for humans to understand and write anyways.
Oh, yeah. My source code is like 60% comments by weight (or more). Although I typically produce separate standalone documentation for management or semi-technical staff. You know, people who know enough to possibly break something, but not enough to fix it afterward. I find it useful when trying to train new people too.
Also writing documentation in-code like JavaDoc or equivalents has always seemed great for me. Then you can have your toolchain generate the written documentation directly from that, and it can be updated easily based on what’s actually documented in the code (but that does require that people keep that updated)
I’m usually on the documenting side of things. If something like this starts unfolding, I produce text or HTML files anyway, they go on github/lab/whatever, and I wash my hands of what happens next.
In the end I write documentation mostly for myself. When the company can’t figure things out over Discord or whatever ephemeral chat interface they use, I get called anyway.
> I produce text or HTML files anyway
I do extensive in-code documentation. The compiler discards all comments so I don’t worry about commenting my code. Source code is for humans to understand and write anyways.
Oh, yeah. My source code is like 60% comments by weight (or more). Although I typically produce separate standalone documentation for management or semi-technical staff. You know, people who know enough to possibly break something, but not enough to fix it afterward. I find it useful when trying to train new people too.
User-facing documentation is a completely different thing, yes.
Also writing documentation in-code like JavaDoc or equivalents has always seemed great for me. Then you can have your toolchain generate the written documentation directly from that, and it can be updated easily based on what’s actually documented in the code (but that does require that people keep that updated)