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

&quot;Don&#x27;t know how&quot;? [A] flaw in human nature is that everybody wants to build and nobody wants to do maintenance (Vonnegut). Most free software projects are entirely built by volunteers contributing what they want to. I don&#x27;t know how much offering classes on &quot;how&quot; would help; it feels like leading a horse onto a boat.<p>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.

Technical writing is dead as a profession.<p>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.<p>This attitude bleeds through to open source&#x2F;free software.<p>You want better documentation? Find a way to compensate people for contributing to it, and that doesn&#x27;t necessarily mean money. Separate your documentation repository from your code base.

This isn&#x27;t just a problem in open source. It is a huge problem in corporate internal software too.<p>Most OSS projects that expect to receive (and actually get) the attention of users or contributors tend to work harder on better documentation.

I was waiting until the dreaded Monday to launch this but I guess I&#x27;ll do a soft launch now since it&#x27;s totally in-topic. I even updated it to add Github&#x27;s Survey results.<p><i>Let me write the documentation for you!</i> I&#x27;ve created this: <a href="https:&#x2F;&#x2F;documentation.agency&#x2F;" rel="nofollow">https:&#x2F;&#x2F;documentation.agency&#x2F;</a> and you can email me so my colleagues and I will write or improve your project&#x27;s documentation. Added a landing page (like <a href="https:&#x2F;&#x2F;picnicss.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;picnicss.com&#x2F;</a> ) and design if you want it. It is <i>for-profit</i> so far, but if everything goes well I&#x27;ll start doing some heavily reduced prices for some OSS projects.<p><a href="https:&#x2F;&#x2F;documentation.agency&#x2F;" rel="nofollow">https:&#x2F;&#x2F;documentation.agency&#x2F;</a>

This is a problem in some really major codebases too.<p>I routinely curse whoever wrote the &quot;docs&quot; for openCV.

I have to laugh at GitHub coming to this conclusion. About 80% of the time when I follow a link to GitHub, there&#x27;s a list of files and absolutely no explanation of what the project is or why one would be interested in downloading or contributing to it. Sometimes there&#x27;s a link to something called &quot;markup&quot; or &quot;markdown&quot; that sometimes has a short description that vaguely describes the project. But that&#x27;s often missing or cryptic, too.

Software suffers from poor documentation principally because those who write the code don&#x27;t have the time or inclination to write documentation, especially if they will have to do it in their own time. Most experienced developers can write well enough but they know that no one will maintain the docs so why bother. In my experience as an internal application developer the documentation is created only when someone leaves or a major application needs to be ported.<p>Internal software is probably the worst because there isn&#x27;t a paying customer in the usual sense of the word so there is no one to send the bill to.<p>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.

As a newbie I often felt repelled by FOSS project I want to contribute to, because even if code is clear and I might have found a piece of code to improve, a lot&#x27;s of project don&#x27;t even include the more minimalist instruction on &quot;how to contribute&quot; &#x2F; &quot;how does my build system&#x2F;doc system work&quot;.<p>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.<p>If your excuse is that you don&#x27;t have time to write doc, maybe don&#x27;t expect a lot of contributors, because guess what maybe they don&#x27;t have time to guess what you didn&#x27;t writeh.

I think there is much potential of new coders wanting to participate to projects, but they just don&#x27;t know how and where. They maybe used a project a bit and stumbeld over bad documentation or not working examples ..<p>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.<p>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 ...

At work we spend a ton of money keeping our documentation up to date, searchable, and available on the web. Worth every penny, and that&#x27;s just if we count the productivity boosts for internal users of the docs.

The frustrating thing about poor documentation is that the product actually works! It&#x27;s just that the creator didn&#x27;t go the last 5% of the way to explain to someone else how. The close-ness of the solution is what makes it frustrating by nature (it&#x27;s not frustrating when you encounter a 2% complete solution to your problem).<p>My point is, the fact that poor documentation frustrates many people according to a survey does not mean that software developers can&#x27;t or don&#x27;t write documentation.

The first thing that came to mind:<p><i>Eagleson&#x27;s Law: Any code of your own that you haven&#x27;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.)</i><p>Writing documentation isn&#x27;t so much a &quot;how&quot; problem, but a &quot;why&quot; problem. Most people writing code in their own time can&#x27;t be bothered also writing documentation for it.<p>Writing code is fun (mostly). Writing documentation is not.

I dont have the time. Train a Neural Net to generate documentation from my rambling and mumbling while editing the source. Do something else to find a solution. I shall write code. With speaking names. With identifyable concepts and algorithms. That must be enough.<p>Also the webs inability to allow the users to meaningfully interact with documentation - by instantly saying -&quot;This step didnt work&quot; 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 &amp; errored in some forgotten config- while he defeats a obsticle - and it should mention those who cleared the path through the djungle as heroes.

And why should they? That&#x27;s not what they test for in interviews.

&gt; Documenting software is extremely difficult. People go to university to learn to become technical writers, spending thousands of dollars, and several years of their life. It’s not really reasonable to expect every developer to know how to do it, and do it well.<p>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.<p>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.

What do we mean by &#x27;documentation&#x27;? Usage of the outwardmost-exported interface (which, depending on the project, may be an UI or an API)? Configuration and customization options, installation instructions? Design rationale, deep-dive into internals, explanation of internal components?<p>&#x27;Documentation&#x27; covers a wide swath of prose, and therefore makes for an easy target for criticism which is in fact very disparate, despite appearing homogeneous.<p>That is not to say most projects have good documentation. Writing prose -- specifically, technical writing -- is a skill orthogonal to software development and doesn&#x27;t necessarily tend to attract the same kinds of individuals.

... and (although to a lesser extent) user interfaces.<p>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.<p>Also, writing documentation and user interfaces isn&#x27;t seen as k3w1 among coders so it&#x27;s understandable that people good at writing docs and&#x2F;or designing UIs are rather doing it for a fee outside the FS&#x2F;OSS world than because they love it.

I see a lot of documentation describing how it works, not what it does. I think most README.md files would be better as code comments. Personally, the most useful documentation contains a brief summery of purpose, usage, and then a few examples. Dependencies should be called out if they are significant.

Is this really a problem? I very seldom run across projects worth using with poor documentation. It&#x27;s usually pretty good.

Open Source is not Free software, nor are most of the projects on GitHub intended for anyone to use. Consider how well documented projects under the GNU banner are. Im sure this is a problem for some projects, but free software is not suffering because of it.