3 ms·
Even some commercial software has poor documentation. Still, open source software has almost universally very poor documentation. I don't know if it hurts free
by BaronSamedi 9y ago
Even some commercial software has poor documentation. Still, open source software has almost universally very poor documentation. I don't know if it hurts free software but it certainly hurts those who use it. If a project is reasonably popular, say a thousand users, and each user on average has to spend an hour to figure out how to use it, then that is 1,000 hours wasted. The developer, could instead have spent say 8 hours writing documentation to save the users that one hour (* 1000).
Contrived example, I know, but the principle holds: time spent by the developer writing good documentation saves users a lot of time. Most developers, in my experience, do not like to write documentation so they prioritize user's needs below their own discomfort.
Some try to take the lazy way out by going the "I'll let the users create the docs on a Wiki" route. See, for example, the Freeswitch (VoIP server) documentation for just how bad this can be.
A lot of developers do want to write good documentation they just don't know how. In this case what we get are reference guides instead of user manuals. Writing small user manuals for OSS projects is not that hard. The key is to put yourself in the user's shoes. Your user wants to accomplish some task with your software, so, in your manual give them step-by-step instructions for how to accomplish it.
It's like writing an algorithm, except that the instructions will run on wetware. For example, to install the software do A,B,C,etc. To compute the standard deviation of your data do 1,2,3 & 4. Spell everything out, just as would do for the computer--assume nothing (ELI5). Don't just give a list of functions.
Users want code that solves their problem with the least possible investment in time and pain. I'm sure many people reading this have been through the OSS pain cycle: find a library that does what you want, see the sparse documentation, and then brace yourself for the pain of figuring out how in the hell to actually use it.
- MichaelGG 9y ago>Some try to take the lazy way out by going the "I'll let the users create the docs on a Wiki" route. See, for example, the Freeswitch (VoIP server) documentation for just how bad this can be. It's terrible. Leads to tons of random settings all over and cargo-culting adding of variables until something happens to work. It's not uncommon for me to find a "documented" variable in the wiki then search the source and not find that string. There's also an attitude of "we wrote the code, be happy for that, and maybe you should figure it out and document it hmm?" Which is totally their right - they did a lot of work for free and people have made tons of money off of it. But it's not a really practical attitude for good docs. I'm guilty of it myself - for mod_managed I wrote some basic docs to get it off the ground but haven't kept them up to date or provided more details.
- vosper 9y ago> If a project is reasonably popular, say a thousand users, and each user on average has to spend an hour to figure out how to use it, then that is 1,000 hours wasted. The developer, could instead have spent say 8 hours writing documentation to save the users that one hour (* 1000). That's true, although it's worth remembering that the 1,000 hours are other peoples time, not the developer's. It might be quite easy for a busy open-source developer (often working in spare time, already) to think "I've got other things I'd rather be doing". Also, it's not just 8 hours one time - it's then ongoing maintenance. So you're spending time in order to create even more work for yourself in the future; documentation that doesn't exist doesn't have to be maintained alongside code changes. We need documentation bounties, or something.
- GregBuchholz 9y ago>We need documentation bounties, or something. ...Are there write ups exploring what "or something" could possibly be? Like futures contracts or options or potentially other risk mitigation practices from the financial world? Something that would help with collaboration and help with getting the timing correct? As in, the best time to have the documentation is at the point, or right before some software becomes "popular". But that seems like the time you are least likely to have enough people contributing to bounties. Is there a way to encourage documentation writing speculators? Is there a way to minimize the bad effects (if any) of winner-take-all bounties in discouraging contributors? That is, for bounties, how do you know if someone isn't already working on the documentation unknown to you, and finishes it (and collects the bounty), one week before you finish your version? And the fear of this prevents people from starting in the first place. Is there a way to make "progress payments" on documentation bounties?
- vosper 9y agoI don't know, but you raise some really interesting points, and we didn't even talk about the quality of the documentation that might be produced. Bounties might be the wrong way to do it, but I can imagine a Patreon-style approach might work. Like "I'm the developer on this, and I'd rather be writing code. But if people contribute $X to my Patreon I will dedicate 5 hours a month to working on the documentation, instead".
- heisenbit 9y agoI fully agree, the developers of open source software are wasting the time of their users. Thinking about it aren't the users in an open source model also developers? Open source software with a sufficient number of users with a clue sooner or later will have sufficient documentation. There is a lot of open source software with bad documentation but most of the open source projects have no traction. This is different from commercial software where some of the dead software never was released. Comparing statistics between the two is oranges to apples.