Ask Slashdot: What To Do About the Sorry State of FOSS Documentation? 430
First time accepted submitter TWX writes I've been out of computers as a serious home-hobby for many years and in returning I'm aghast at the state of documentation for Open Source projects. The software itself has changed significantly in the last decade, but the documentation has failed to keep pace; most of what I'm finding applies to versions long since passed or were the exact same documents from when I dropped-out of hobbyist computing years ago. Take Lightdm on Ubuntu 14.04 for example- its entire configuration file structure has been revamped, but none of the documentation for more specialized or advanced uses of Lightdm in previous versions of Ubuntu has been updated for this latest release. It's actually harder now to configure some features than it was a decade ago. TLDP is close to a decade out-of-date, fragmentation between distributions has grown to the point that answers from one distro won't readily apply to another, and web forums for even specific projects are full of questions without answers, or those that head off into completely unrelated discussion, or with snarky, "it's in the documentation, stupid!" responses. Where do you go for your FOSS documentation and self-help?
*BSD has best-of-breed documentation. (Score:5, Insightful)
The one thing Linux really, really lacks, compared to the *BSDs is the quality of the documentation. Not even Google makes up for the deficiency.
Real men (Score:4, Insightful)
I jest, of course. It's not just open source projects that have this problem, though; plenty of commercial applications also have shit for documentation. The upside in open source being that you *can* read the source and build documentation from it, if you were so inclined.
Re:Read the source code (Score:5, Insightful)
Re:Read the source code (Score:5, Insightful)
I've never seen JavaDocs that add anything to the source. It's okay if you need a list of methods or parameters, but usage is lacking.
Documentation needs to have several *working* examples (not snippets) from a simple Hello World to more sophisticated but still commonly used. A single example that illustrates every imaginable feature and use case is rarely helpful.
Software Documentation is bad everywhere (Score:4, Insightful)
The problem is most software is complex, and documentation is an attempt to simplify the work flow. But the documentation if complete would probably be just as large if not larger then the code, and just as complex to read.
What I find for good documentation is down in the FAQ, or a quick spot where you know a particular area is kinda clunky in the UI, or just a list of of the features you can use and what they do. Not a formal write up in a 1000 page book. But the appendix, and the list of tables is usually enough.
Re:It's open source (Score:5, Insightful)
That sort of attitude is the problem.
Building the application and writing the code is half of the project. The other half is documenting it. Yes, you'll spend twice as much on the project, but that's counterbalanced by someone else picking up and improving it a lot faster.
Also, undocumented code is a half-assed job, no matter how well it performs.
Big problem: Linux won (Score:5, Insightful)
A huge amount of documentation for various projects like GNU groff, GNU nano, Vim, and others, have implicit assumptions that users are familiar with those tools' traditional Unix counterparts. 'man nano' for example, doesn't describe any of the keybindings for the editor, instead assuming that users already know pico. The groff documentation in places explicitly states that it only documents the difference between groff and Unix troff.
Linux has won. Most Linux users have never used a traditional Unix, and most never will.
Corrected Title (Score:5, Insightful)
Re:Software Documentation is bad everywhere (Score:4, Insightful)
"documentation is bad everywhere" is one of those lies developers tell themselves to help them sleep at night. There are programs out there with outstanding documentation. (For example, as a grad student who had never toughed MatLab before I was easily able to teach myself in about a week by just scrolling through the help files.) It's just that those programs are rare, and almost none are FOSS.
This makes sense, because involvement in projects is voluntary, and contributors choose where to dole out their time. There are generally no "customers" with a carrot and stick to make the developers sweat about their failures and oversights. It makes sense that almost no one choose to spend time documenting. Even if they understand that it's a necessary pain, no one wants to be stuck doing in.
The solutions would have to be institutional. I can't think of a single OS project I've seen that had something like "decent documentation for new features" as a gating condition for a major release. That kind of cultural change is hard (and unlikely), but needs to be done if anything is to be accomplished. The only alternative is automated documentation, which doesn't really do anything more than re-state the source code in a different form. It's still only useful if the developers are religious about updating meta-code comments, which they never are.
Re:Real men (Score:5, Insightful)
That's because documentation isn't fun or glamorous. Everyone developing FOSS wants to do all the fun programming stuff. But no one wants to do the boring hard work of documentation, UI polishing, promotion/marketing, etc. That's why FOSS tends to suck in those areas compared to the commercial stuff (where they actually pay technical writers, designers, marketers, etc.)
At least the neckbeards weren't hipsters. (Score:4, Insightful)
You think it was bad then? Well, I'm not saying that it wasn't, but it has gotten a whole lot worse lately.
The neckbeards you speak of are now in their 50s and 60s. A lot of them have, I'm afraid to say, died. They didn't live the healthiest lives when young, and they have perished because of this. A lot of the others have been marginalized as we've seen the hipster tide sweep in.
At least the neckbeards had real experience. Most of them had gone to college, and a lot of them had graduate degrees and decades of industry experience. They may have been assholes at times, but at least they were competent. They wrote good code, even if they didn't always provide documentation.
The hipsters have none of this. Most of them are in their early 20s, if not younger. They have no real education. Their knowledge is extremely limited, but they don't realize this. This is why they think JS is a good programming language, for example. They have absolutely no idea about anything else. The software they write is typically total crap, and documentation is completely foreign to them.
At least the neckbeards could be depended upon to provide useful information about how their software worked. Maybe it'd take some fighting with them, but eventually the information would come out, and it would be correct. It's a different ballgame with hipsters. They don't know how the software works, even when they wrote it. When they claim to know how it works, they actually don't. So if you're trying to write documentation for their code, not only do you have to deal with shitty code (assuming you know how to), but you can't even rely on the developers themselves to know how it works, how to use it, or what it's even supposed to do.
As somebody who has contributed documentation for several neckbeard-run projects and several hipster-run projects, I would be more than happy to deal with the neckbeards any day. It isn't a good experience, but it isn't a total clusterfuck like it is when dealing with hipsters.
Hello Grumpynerd? (Score:5, Insightful)
"Incomplete Documentation
Open Source nerds don't have the discipline to write documentation because it's no fun. Writing new code is fun. Fixing bugs in old code is less fun. Writing documentation sucks. Which is why most open source software is buggy and features little to no documentation making it useless to everyone outside of the authors".
http://www.grumpynerd.com/?p=1... [grumpynerd.com]
Re:Nothing (Score:0, Insightful)
I'm shocked that no-one wanted to work closely with you.
Google it (Score:0, Insightful)
Re:Software Documentation is bad everywhere (Score:5, Insightful)
Have you ever USED IBM, Oracle or MS software?
I've run into scenarios with both IBM and MS where I'm looking for a specific error code, and I get into this:
Q: What is ERR:174027?
A: That's EDONTKNOWWTF
Q: What is EDONTKNOWWTF?
A: That's ERR:174027
*Bashes head into wall*
Commercial software might have better documentation, but a lot of the help still comes from blogs of people having the same error, which IS NOT documentation!
Yes, proprietary (commercial) often wins here (Score:4, Insightful)
I will just wind up using proprietary software with proper documentation.
Same here.
I love the idea of Open Source, community-driven projects, and I'm happy when they provide useful software to people for no cost, and I'm happy that there are people providing competition for the big name software companies.
I'm also a busy person. If I've got work to do or something important to finish personally, then realistically the cost of buying more polished commercial/proprietary software can often be justified instantly.
That might be because it has comprehensive documentation, but much the same applies to the usual FOSS weaknesses: ease of use, or compatibility with industry standards, convenient availability of professional consultancy and training, and so on.
(Of course, I am similarly sceptical about proprietary commercial software where the documentation or ease of use don't justify the high prices sometimes asked. This isn't about FOSS, it's about whether it's worth spending real money to get a much more practically useful product.)
I don't usually bother (Score:4, Insightful)
Where do you go for your FOSS documentation and self-help?
Documenting code is different than documenting an interface. As an end user I honestly I don't bother with FOSS documentation for the most part because it's generally so bad. (Sadly non-FOSS software is too seldom much better even when it should be) While there are times when I have to dig into whatever is available, I generally don't bother with any application (FOSS or not) that I need to consult the documentation to figure out unless I absolutely have no alternative. It's sort of a quick and dirty way of sorting out what I want to use since 99% of what I do does not require deep magic. If I have to get out the manual then chances are that the application is poorly designed and will most likely cost me more time than some alternative. There are exceptions of course but it's not a bad first pass filter.
As a random example it's why I can't be bothered with EMACS despite the fact that it's an absurdly capable piece of software. (I don't like vi either so spare everyone the holy war) If I have to consult a manual to do even the most basic things in the application then it isn't worth my time. (Ctrl-x Ctrl-c to quit? Seriously?!? No thanks) I don't want to memorize a random list of key shortcuts especially for an application I'm just starting to use. Installation routines should take care of all but the most arcane issues. Applications should never require magic keystroke combinations or buried options for common tasks. Minimalism is fine but not when it hides so much that I can't immediately discern how to do a task (I'm looking at you Apple). If I need a tooltip to figure out what something does then it is badly designed. If I have to pull up a help screen (press F1 etc) then it is really badly designed. If I have to look at a man page or consult a third party reference then it is probably completely broken.
I think good documentation is important but it should never be a substitute for a well designed interface. Furthermore documentation for users (code is different) should primarily serve two purposes. 1) To get people up to speed on basic tasks with an unfamiliar application and 2) To document weird corner cases and how to deal with them. 99% of what any application does should not require special documentation. If it does then it needs to fixed until it is in a state where it no longer needs the documentation.
Re:Read the source code (Score:5, Insightful)
That is completely unreasonable. If I have to read the source code just to be able to understand how to use the program, I will just wind up using proprietary software with proper documentation.
On the other hand, I've noticed a steady decline in documentation for commercial software too. Manuals have gone from the thick reference books I remember from 20 years ago to little "quick start" books if you're lucky. More frequently no documentation at all.
Self documentation is going downhill too - there seems to be a trend to removing UI hints such as the short cut keys from menus, so where you would discover stuff from clicking around in the UI and seeing it, now it frequently seems that you'll never figure this stuff out without googling for an answer.
Error messages, too, have disappeared - back in the day you used to get a descriptive error that told you what broke. Ok, so the non-techies probably didn't understand them but at least they could ask a techie. Over the past few years, error messages have been replaced with generic "something broke" errors that give no one any hints as to what went wrong. Increasingly (especially on Android and iOS) apps don't display an error at all - if something breaks they often just plain don't work and its very difficult to figure out why.
Re:*BSD has best-of-breed documentation. (Score:3, Insightful)
This is impossible. In the Linux world, everything is always a moving target. The reason that *BSD documentation is good is because things are often designed, implemented and then documented. The FreeBSD handbook does get revised frequently, but usually just to document enhancements rather than complete changes in how everything works.
For a Linux distro like Ubuntu to have stable documents, they'd have to actually stick to a sound system, init system and so forth for awhile and not play musical chairs.
Re:It's open source (Score:5, Insightful)
If someone comes along and gives you a free hamburger, you don't complain that they didn't bring fries and a drink.
But if the hamburger tastes bad and you are not sure what's in it,. you might want to ask. And if you ask and are given an answer like "hey it's free, eat it or GTFO" it doesn't make the giver less of an asshole.
Developers often still get paid (Score:2, Insightful)
Free software is....well...free. The people who wrote it don't get paid.
Frequently that is not at all true. Most free software is developed by professional developers in conjunction with their day job. It is released as free but for many important software projects the developer probably actually did get paid for their time. Sure there are a non-trivial number of developers who really are doing it for non-financial reasons in their spare time but the number is far smaller than most people think.
Bad documentation is not unique to FOSS. Commercial software is often just as bad.
Hence, "Software Engineer" == MYTH (Score:5, Insightful)
... and this is why the term "software engineer" is a bit of a misnomer.
Could you imagine if, say, aerospace engineers didn't document their work? Automotive engineers? I can hear the shop talk now:
"Hey, Jim, what's the recommended torque for head bolts on an '09 Madza 3?"
"What's the manual say?"
"Nothing, they didn't document that part."
Ergo, coders who fail to document are anything but engineers, cocky attitudes aside.
Re:Read the source code (Score:5, Insightful)
I think several here have different expectations of what constitutes "good documentation". Being a Linux sysadmin, I work in FOSS day in, day out, and documentation is always available and clear.
Without knowing, you've hit the nail with the hammer.
.pdf document with all possible options.
Here is why FOSS docs are so nice to you, but proprietary ones are not: audience analysis.
The people who create FOSS documentation are often either the developers themselves, or very early adopters who spend a lot of time with the developers. They have a technical mindset, and will write documentation in that way. You have a very technical mindset, and like me, will probably prefer a well-commented configuration example over a nicely formatted
In large enterprises, things are different. That's where the professional technical writers come in (yes, that's a full-time job). These folks will come up with a target audience, secondary audience, initial outline for the documentation and (in their minds) well-written content and examples. Since this gets reviewed many times by people who all have an ego telling them that they must make at least some changes in order to show productivity to their bosses, the documentation ends up being a piece of crap. It may be correct, but it usually is a piece of crap. For example, let's take any routing vendor's documentation. You are looking to configure something as simple as an L3VPN. The easiest way to do this is by getting an example configuration and just change some IP addresses to match your own network, right? Well, the "professionals" think not. They will come up with this:
Step 1: configure an IGP. For more information on how to configure an IGP, see chapter 12, section 3.
Step 2: enable the appropriate interfaces for MPLS. For more information on how to enable interfaces for MPLS, see chapter 2, section 1.
Step 3: create an LSP between the two PE nodes. For more information an how to configure LSPs, see chapter 2, section 10.
Step 4: enable a signaling protocol such as BGP or LDP. For more information on how to configure BGP as an L3VPN signaling protocol, see chapter 10, section 9. For more information on how to configure (targeted) LDP as your L3VPN signaling protocol, see chapter 7, section 1.
Step 5: configure the route-target: set route-target 12345:1. For more information on route-target configuration, see chapter 8, section 2.
Step 6: configure the route-distinguisher: set route-distinguisher 12345:100. For more information on route-distinguisher configuration, see chapter 8, section 3.
And that, my friend, is why commercial documentation sucks a monkey's ass.
Re:Corrected Title (Score:2, Insightful)
Except that IBM, Microsoft, Apple, etc all have extensive documentation with examples. It's basically open source that sucks in this regard.
I don't agree with you on this. Microsoft and Apple have documentation, but I find the documentation pretty bad too, once you get past the "user" level stuff and "Quick Start" guides. I don't have much experience with IBM documentation but I cannot imagine it's all that much better. What I would say is that Microsoft, Apple (and I presume IBM) actually have customers who expect documentation at some level and are willing to pay for it. These same customers are usually willing to pay for phone support too, so you can bet the *real* scoop is saved for the money making phone calls.
So for FOSS, the same model applies, except there is NO profit in documentation, unless you write the definitive guide for something really popular like Wall did for Perl. There is nothing that says you cannot CHARGE for support of FOSS you know, which means if there is some project worth using for you, then offer to PAY for support. That's what Red Hat does for the most part. If the FOSS project is so short sighted that it provides no documentation and the development team won't help or just says "read the code" then it seems to me that there is a business opportunity here. You can figure it out on your own, write a document, either give it back to the project or publish it for profit and sell support services.
Re:Read the source code (Score:4, Insightful)
Good documentation in my experience is documentation that any competent programmer/engineer/user can pick up and immediately use without ever having seen your stuff before.
Re:Corrected Title (Score:2, Insightful)
Microsoft honestly has some of the worst documentation out there. (for a commercial product).
Just try looking up how to do something in Visual Basic for applications or whatever it's called now.
There are two or three different websites where you have to look for information.
Sometimes the actual information is wrong, misleading, or just not there.
In those cases usually the comment section explains what's going on.
The search on their page doesn't help either, the whole thing is useless without google.
So yeah, I wouldn't be using microsoft as an example of good documentation.
Re:Nothing (Score:1, Insightful)
No. My communication skills are fucking excellent when I'm not shitting all over someone for being an asshole to me. Believe it or not, not everyone is a boring fuck like yourself. Some of us are actually capable of communicating in multiple ways depending on the setting.
Re:Read the source code (Score:3, Insightful)
Setting up a resource like that doesn't mean that it's filled out in a useful way, and it's not.
Re:Yes! (Score:0, Insightful)
Let me tell you why I stopped using Linux.
I stopped using Linux because of Debian.
Keep in mind... by this point I'd been using Linux as my sole OS for over three years. Three years. I knew how to work the fucking thing. I had switched from Fedora to Debian due to some idiotic religious compatibility issues keeping me from using the sound software I wanted to use. I was merrily Linux-ing along and then, one day, Debian pushed a new update. Hooray! The crowds rejoiced! Everything was awesome 'cause it was a new kernel and a new UI and it was going to be SUPER! So I popped open the package manager and did the update dance. I restarted my computer so I could install the nVidia drivers (more religious bullshit) and noticed something weird... my hard drive was gone.
Motherfucking WHAT?
Reboot again and let it all load this time. It booted up into Debian just fine... but it was running off of the OS's partition and didn't even list the other 29 GB of space I had. I had no fucking clue what to do. I ran the partitioning program and it could see that the hard drive was 30 GB... but it listed 29 of it as unavailable.
Motherfucking WHAT?
For some reason I couldn't partition that space. I hadn't wiped the drive before, so all of my stuff should still be on there... right? Okay, I'll just search for a filename that I know exists on the hard drive.
My fucking hard drive had been moved from /dev into /etc. All of the contents had been moved from /dev/hdd0 (or 1, I can't fucking remember) into /etc/somefuckingpath. Okay... all of my shit is still there. If I do straight to that directory I can still access all of my programs and files and everything else. Now how do I get that shit back?
Should be a simple enough answer, but I still don't know.
I went straight to the Debian forum and explained the situation very clearly. I updated. My stuff is borked. How do I unbork it?
Days passed with no answer. In the tech help forum. Of Debian. I bumped the thread once and got bitched at for bumping old threads. I posted a new thread and got bitched at for doing THAT.
Fine, I'll try a more direct approach and see if someone in the IRC help channel can assist me. I pop in, ask my question, and fucking immediately have one of the primary fucking developers (I shit ye not) jump up my ass for insinuating that their software could EVER do something like that. It was MY fault that the installation was fucked up. "You fucked it up, you figure it out." No, you fucking prick, your package manager fucking broke it you miserable fuck. I followed the instructions that YOU FUCKING WROTE, asshat.
I grabbed my old Windows disk, put it in the drive, rebooted, installed over Debian, and have never looked back.
None of my interactions with the Linux "community" were positive. Unless you are a programmer you are worthless to them.
Fuck them and their fucking high horse.
Linux: Not even once.
Re:Bring back man pages as the primary documentati (Score:4, Insightful)
I wouldn't say that today's software is too complex for man pages but instead man pages have never really been ideal for the tasks for which they're used. Software has always been complex. Man pages might have been appropriate for some short window of time but technology quickly left them behind.
Man pages do not have an effective system of hyperlinking, indexing, or even searching. They were meant to be read on a teletype or printed on paper. For documentation any more complex than instructions on how to use console commands they are completely inadequate. Even for looking up instructions on console commands they're less than adequate because there's no sort of authoritative hierarchy, if you don't look up the exact right term man won't point you to the correct documentation (or best guesses).
Besides man being inadequate it is difficult to write proper man pages. This is just adding insult to injury as it makes it less likely that developers will write even bad documentation.
Of existing documentation systems I'd most like to see GNU Info become the primary documentation mechanism for FOSS. It solves most of man's problems without introducing its own new ones. Even GNU Info isn't perfect and could use some improvements.
I don't disagree with the idea that FOSS desperately needs some reliable offline documentation. This idea might require that FOSS distributions themselves maintain their own documentation. The Arch wiki for instance is fantastic, it's some of the best Linux/Unix documentation around. While the Wiki is great it would be really nice to see this information turned into texinfo/manpage/whatever files so everyone could have good references and not need access to the internet.