News for hackers. Stuff that matters.
Re:Why programmers don’t write documentation by 29athrowaway on Saturday May 01, 2021 @01:17PM (#27007940)
Hire a technical writer.

Not only for your external documentation... for all of it.

If you are afraid of the costs, do the math.

1 technical writer for every 20 developers.

Re:Why programmers don’t write documentation by zabzonk on Saturday May 01, 2021 @02:06PM (#27008393)
Now you have one more problem (several, in fact) - explaining the business and the software to the technical writer. This is so difficult, that in all my long career in software development and management, I never saw any company specifically hire a technical writer, though I have done a lot of technical writing myself, on the side.
Re:Why programmers don’t write documentation by 29athrowaway on Saturday May 01, 2021 @04:36PM (#27009593)
The technical writer can be involved in the release management and ask for details that then he can use as a starting point.

They can help identify gaps in documentation, outdated documentation, etc. They can take care of the clarity, formatting and distribution. You can create a ticket about documentation and assign it to them.

Then, while many developers write excellent documentation... some other developers truly SUCK at documenting. Some people like to sound intelligent and their comments read like a choose-your-adventure monologue that cannot be read linearly. Or they use vague, ambiguous language, or overuse acronyms or abbreviations. Or they sign every piece of code they touch like a dog scent marking your entire code base. Or they use profanity, or they get offtopic or humorous... All of that is a distraction from doing my job.

The technical writer takes care of those problems for you. They can create guidelines for documentation so that people treat documentation with the respect it deserves.

Re:Why programmers don’t write documentation by zabzonk on Saturday May 01, 2021 @05:14PM (#27009879)
About as much could be expected from a throwaway account.

> All of that is a distraction from doing my job.

What job would that be? Do you actually have one?

Re:Why programmers don’t write documentation by 29athrowaway on Saturday May 01, 2021 @05:27PM (#27009999)
> About as much could be expected from a throwaway account.

For privacy reasons as this is indexed in search engines and comments cannot be deleted after 1 hour, forever.

> What job would that be? Do you actually have one?

I do, and it's none of your business.

If you want to participate in a community with an expectation of real life identity go have your discussions on Facebook or whatever.

Re:Why programmers don’t write documentation by maya24 on Saturday May 01, 2021 @02:55PM (#27008807)
This is a terrible solution. Writing is part of the developers job requirements. And writing doesn't just happen in documentation. It happens in emails, technical specs, presentations, code comments. Developers should maybe just get better at their job because documenting and writing is part of it.
Re:Why programmers don’t write documentation by 29athrowaway on Saturday May 01, 2021 @04:33PM (#27009569)
Writing is part of developer job requirements, sure.

Is technical writing part of your interviews? do you hire, promote or fire people based on technical writing performance? Is documentation taken as seriously as other code deliverables?

Why paying an expensive senior developer to maintain documentation in a non-commited way when you can pay a technical writer to do it better and for cheaper than the engineer can? And with real ownership and accountability over documentation, unlike the engineers.

Technical writers are cost efficient and pay themselves very quickly.

Re:Why programmers don’t write documentation by watwut on Saturday May 01, 2021 @02:43PM (#27008685)
100% this.