Free software is suffering because coders don’t know how to write documentation

Also, the poll seems a suspect way to support the idea that more documentation is justified; I agree with that idea, and TFA has other arguments supporting the point, but I question the utility of the poll as an argument. Developers would like better documentation of the libraries they are using, but they would. In a Pareto-optimal scenario where exactly the right amount of work was put into documentation, developers would still want better documentation. And I would want a pony.

Too many companies expect technical writers to be as savvy, or more, as their developers, but for lower pay, less respect, and zero political power.

This attitude bleeds through to open source/free software.

You want better documentation? Find a way to compensate people for contributing to it, and that doesn't necessarily mean money. Separate your documentation repository from your code base.

Most OSS projects that expect to receive (and actually get) the attention of users or contributors tend to work harder on better documentation.

Let me write the documentation for you! I've created this: https://documentation.agency/ and you can email me so my colleagues and I will write or improve your project's documentation. Added a landing page (like https://picnicss.com/ ) and design if you want it. It is for-profit so far, but if everything goes well I'll start doing some heavily reduced prices for some OSS projects.

https://documentation.agency/

I routinely curse whoever wrote the "docs" for openCV.

Internal software is probably the worst because there isn't a paying customer in the usual sense of the word so there is no one to send the bill to.

Do technical writers still exist? I could write documentation, in fact I intend to spend three days next week doing just that, but someone who has that as their primary skill would do a better job; unfortunately the company no longer employs such people.

If you are doing thing really standard, point to the standard doc of you build system. But most of the time first think you have to do is to spend days trying to guess how the fuck the project is organized.

If your excuse is that you don't have time to write doc, maybe don't expect a lot of contributors, because guess what maybe they don't have time to guess what you didn't writeh.

So in theory, helping with documentation and fixing that would be a good start for them. But it takes confidence to tell someone, especially when you are a newb, that your documentation is sh*t and that you could help with that.

So if projects are more open for that - and explicitly say that, that they are open and thankful for that(also for beginners) - it could be a huge benefit for everyone ...

My point is, the fact that poor documentation frustrates many people according to a survey does not mean that software developers can't or don't write documentation.

Eagleson's Law: Any code of your own that you haven't looked at for six or more months, might as well have been written by someone else. (Eagleson is an optimist, the real number is more like three weeks.)

Writing documentation isn't so much a "how" problem, but a "why" problem. Most people writing code in their own time can't be bothered also writing documentation for it.

Writing code is fun (mostly). Writing documentation is not.

Also the webs inability to allow the users to meaningfully interact with documentation - by instantly saying -"This step didnt work" and getting then feedback from so god forsaken irc-channel or mailinglist. There is no real integration of the users ability to contribute to documentation. And wikkis are the worst at this. The tagged syntax, the time wise seperation from the point of usage of the documentation.. it all adds barriers, where there should be none. Documentation should not be added online at some remote site.. documentation should be generated by the user, while he is tryialed & errored in some forgotten config- while he defeats a obsticle - and it should mention those who cleared the path through the djungle as heroes.

This is the answer. Software developers are bad doctors, and bad writers, and bad musicians, ... Why do people expect that software developers should have so many other professional skills? The time when your developer designed, implemented and written content for your corporate web is long gone. But we still expect them to be good technical writers.

In the companies I have worked for, we have technical writers that help to write organized, consistent complete documentation. And it is a full time job.

'Documentation' covers a wide swath of prose, and therefore makes for an easy target for criticism which is in fact very disparate, despite appearing homogeneous.

That is not to say most projects have good documentation. Writing prose -- specifically, technical writing -- is a skill orthogonal to software development and doesn't necessarily tend to attract the same kinds of individuals.

Writing software, its documentation and its way to interact with the user are three totally different beasts requiring different skill sets: documentation and UIs should be written with people in mind, not algorithms, so better not leave that task to a programmer.

Also, writing documentation and user interfaces isn't seen as k3w1 among coders so it's understandable that people good at writing docs and/or designing UIs are rather doing it for a fee outside the FS/OSS world than because they love it.