Slashdot Mirror
Ask Slashdot: What To Do About the Sorry State of FOSS Documentation?
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?
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.
learn how to use a program by reading the source code!
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.
Writhe your naked ass to the mindless groove.
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.
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.
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.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
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.
...but it's being eaten...by some...Linux or something...
Ask Slashdot: What To Do About the Sorry State of All Software Documentation Everywhere?
I find being offended by me offensive.
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.
"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...
"Kill 'em all and let Root sort 'em out"
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!
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.
http://blog.nexusuk.org
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.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
... 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.
An enigma, wrapped in a riddle, shrouded in bacon and cheese
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.
I'm not a complete idiot... Some parts are missing.