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 best thing to do is avoid GitHub projects. The GitHub culture is all about spewing out a lot of shitty JavaScript or Ruby code really quickly, making it public using git, then never bothering with real releases or documentation or anything else that's associated with software project management.
Software not hosted on GitHub is almost always a lot better. The fact that it's not hosted at GitHub means that the developers are at least capable enough to set up their own infrastructure, or at least use a hosting platform like SourceForge that encourages real software releases. These developers aren't just about shitting out shitty Ruby or JS code snippets. They're about putting together open source software products, which includes providing regular tested releases and good documentation.
I can't think of the last time I've gone to a project hosted on its own website or even on SourceForge and had a problem finding useful documentation. Sometimes you may need to build from source to get the documentation generated fully, but at least it's there. This is totally the opposite of my GitHub experience, where I often find code with no comments at all, no documentation, and not even a readme file. It has gotten to the point where if a project is hosted at GitHub, I just won't even bother. It likely won't be worth my time trying to deal with its lack of documentation and its horrible source code.