News for hackers. Stuff that matters.
Re:Theory-building and why employee churn is lethal to softw... by layer8 on Tuesday January 10, 2023 @05:16PM (#34332331)
> 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 are 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 a bit like tech debt, just documentation debt.

While writing good documentation isn’t easy, the fact that it usually gets neglected is a cultural issue.

Re:Theory-building and why employee churn is lethal to softw... by BlueTemplar on Tuesday January 10, 2023 @06:38PM (#34333045)
Any examples of great documentation ? (For open source of course.)
Re:Theory-building and why employee churn is lethal to softw... by layer8 on Tuesday January 10, 2023 @07:58PM (#34333627)
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
Re:Theory-building and why employee churn is lethal to softw... by BurningFrog on Tuesday January 10, 2023 @07:55PM (#34333612)
My take:

People "on the spectrum" are not great communicators, and also struggle to understand what it is other people know and don't know.

Also, documenting is genuinely hard, even if you don't consider that it changes all the time. Which it typically does.

Re:Theory-building and why employee churn is lethal to softw... by layer8 on Tuesday January 10, 2023 @08:06PM (#34333676)
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.
Re:Theory-building and why employee churn is lethal to softw... by halkony on Tuesday January 10, 2023 @08:07PM (#34333677)
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.

Re:Theory-building and why employee churn is lethal to softw... by Aeolun on Tuesday January 10, 2023 @08:52PM (#34334098)
Everyone is on the spectrum. Coders are just closer to one side of it :)
Re:Theory-building and why employee churn is lethal to softw... by BurningFrog on Tuesday January 10, 2023 @09:09PM (#34334217)
I am strongly implying that, yes!
Re:Theory-building and why employee churn is lethal to softw... by bentobean on Tuesday January 10, 2023 @09:47PM (#34334462)
You can do surprisingly well in this line of work by simply not being an asshole.
Re:Theory-building and why employee churn is lethal to softw... by BurningFrog on Wednesday January 11, 2023 @10:59AM (#34339871)
Yeah, the social skills threshold is amazingly low...
Re:Theory-building and why employee churn is lethal to softw... by fexecve on Wednesday January 11, 2023 @12:33AM (#34335349)
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.