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.
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 am saddened to say that the lack of proper, structured documentation, combined with bad experience every time I asked a question on OFSS forums kept me away from OFSS in general (and Linux, more specifically). Every year I try again and I am seeing the same results.
I know I might ask questions perceived as "stupid" but everyone's been a newbie at some point in time. Maybe it's just my turn to be one. Thing is, once I get the correct, detailed answer I never ask the same question again but I almost never get the answer, just "RTFM" and "haha noob" with the obligatory variations.
Of course, I've been trying to ask very specific questions, I've provided detailed information on my issue and was very polite myself. Still was met with smug and bile.
In all fairness, creating documentation is something that almost nobody wants to do. I get that. However, politely answering a question shouldn't be that difficult.
...gis sdrawkcab (usually not responding to ACs; don't bother posting as AC)
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!
On the other hand, I've noticed a steady decline in documentation for commercial software too.
Many of them seem to be going the route of "community-driven" documentation; i.e., dropping the cost of the manuals (and everything related, such as tech writers, printing, and so on), and shifting the burden of educating new users to more experienced ones. This is more or less how most FOSS projects have been documented for years, though out of necessity rather than a desire to cut yet another corner.
Writhe your naked ass to the mindless groove.