> documenting the internals of a complex piece of software is a rare skill. A skill that most developers don’t possess.
I believe this is partially due to lack of training (technical writing rarely gets trained, and companies rarely invest in it as a skill), and sometimes probably also due to lack of exposure to high-quality documentation (which serve as role models you’d then want to live up to in your own documentation).
In addition, companies often do not reward expending time and effort on writing documentation, because it isn’t crucial in the short term. It’s similar to tech debt, just documentation debt.
While writing good documentation isn’t easy, the fact that it usually gets neglected is a cultural issue.
I agree that not everyone has a knack for it. But I don’t think that’s the only factor. Software design/architecture is also hard and many devs aren‘t particularly good at it. We still recognize it as an important skill that requires education and training (and experience). If even just 20% or so of devs would get up to speed with how to write adequate documentation, and were enabled to invest the necessary time for it, that would already be a huge improvement.
Are you implying that a significant amount of coders are "on the spectrum"?
Not that I disagree -- working in highly technical fields this long, I could categorize 80% of my co-workers as lacking typical social and communication skills and you never know the real reason. It's to the point where I see women get promoted to management roles more often because they're superior communicators.
I think that technical communication isn't the same as other communication, so I don't think it's a logical given that people "on the spectrum" would be bad at it. Technical communication is about conveying technical information, at various levels, with just a few constraints. It's a solved problem, really. It just needs to be followed to the letter.
I have no particular recent examples in mind, though I believe the Rust documentation is pretty good. Maybe browse these search results where similar questions have been asked previously: https://hn.algolia.com/?query=documentation%20examples
I believe this is partially due to lack of training (technical writing rarely gets trained, and companies rarely invest in it as a skill), and sometimes probably also due to lack of exposure to high-quality documentation (which serve as role models you’d then want to live up to in your own documentation).
In addition, companies often do not reward expending time and effort on writing documentation, because it isn’t crucial in the short term. It’s similar to tech debt, just documentation debt.
While writing good documentation isn’t easy, the fact that it usually gets neglected is a cultural issue.