If the average technical document was useful and clear, I think more people would be inclined to read whatever you're handing out.
It may be that your coworkers are so used to the piss-poor quality of average documentation that they don't bother-- even if yours is high quality. I can't blame them.
Most documentation I've seen is some combination of:
- Inaccurate
- Verbose
- Poorly organized
When I'm handed a 20 page document consisting mostly of lengthy paragraphs, I generally opt out and just go look at the code.
I'm much more likely to read further if a document leads with:
- A single-sentence summary
- A 5(ish) bullet overview
- Prerequisite knowledge
It signals that I'm in for a better-than-average read.
Incidentally, the Google course[0] or the equivalent is excellent.
It may be that your coworkers are so used to the piss-poor quality of average documentation that they don't bother-- even if yours is high quality. I can't blame them.
Most documentation I've seen is some combination of:
When I'm handed a 20 page document consisting mostly of lengthy paragraphs, I generally opt out and just go look at the code.I'm much more likely to read further if a document leads with:
It signals that I'm in for a better-than-average read.Incidentally, the Google course[0] or the equivalent is excellent.
[0] https://developers.google.com/tech-writing