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?
ARCH LINUX WIKI (Score:5, Informative)
I have found https://wiki.archlinux.org/ [archlinux.org], the Arch Linux Wiki to be the most useful single source of information taht is generalized enough to apply to most other distributions.
As an early adopter of Linux, I too found the existing documentation appalling and started writing better documentation, which led to co-authoring RedHat/Fedora Unleashed with Bill Ball.
My advice is to contribute to the documentation yourself since it appears that no one else, including the software authors, care much about it.
But the barriers to contributing are high. You may not only need to learn about the application, but you need to learn any number of arcane editing and versioning tools, and then convince someone in authority to accept and include your changes. It's really no different that contributing code to a project and for your average writer, that's a huge hassle and likely a big part of why more writers don;t contribute.
Re:Software Documentation is bad everywhere (Score:5, Informative)
Not everywhere. One free software project has the best documentation [postgresql.org] I've ever seen. We need to point people at shining examples of excellent documentation so they can realize how important it is.
Terrible coding standards (Score:5, Informative)
I'm a rather odd duck. I did a lot of coding in college and my first job (writing software for hospitals) but have since moved to system administration/design and have a degree in technical documentation. I've written books on Linux and have documentation up on the LDP, some of which is still in use. So I've seen all the sides.
Coders are too busy writing code and making changes to what they write to give time for accurate documentation to be written. The days of "read the code for documentation" are long gone when you have multiple layers of libraries and applications to go through to find what you're looking for. This kinda worked in the days when you could fit an entire Linux install on three floppies but now that you need a few GB there's no way a single human can keep track of it all. Documentation takes time to write and get right. In the age of using github as a distribution and code changes between today and tomorrow, the documentation is suddenly invalid before it's written. Even then, it requires a lot of stupid questions asked by the documentation staff to coders who think they have better things to do.
As for TLDP there was a bunch of problems. Using DocBook was brilliant, but the toolsets were terrible to work with and difficult for people who never used SGML or XML. Linuxdoc was easier to use but really wasn't the way to go long term, especially since the tools were Linux-only and meant the tools were of limited use. Once Wikis took over online there wasn't enough enthusiasm in TLDP to convert and lead the charge.
Writing Manuals and Documentation (Score:4, Informative)
However, it isn't terrific AND I worked as a technical author for a number of years, doing mainframe software manuals. This is my main point, good manuals [mine is not] are hard and probably require equivalent effort to the software itself. The other big obstacle is that in, for example, mainframe world there is formal review process, formalised customer feedback, errata etc. etc. Also, manuals are planned as a 'set' installation, operation, troubleshooting, API etc.
I don't know a lot of my customers and can only correct things that appear in the Google group. In my case, since it's a niche. there's not very much.
Actually there's an opportunity here as well, in that non-code people could also participate in their favourite projects by writing guides. Indeed sometimes they do, but not often enough and they're fragmentary.
Re:Read the source code (Score:5, Informative)
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.
Bring back man pages as the primary documentation (Score:4, Informative)
I think Unix (not just BSD, but I include BSD-based SunOS 4.x) documentation from the mid 90's was the best and easiest to follow.
The main thing I miss from that era is that practically everything I wanted to know could be looked up in man pages; and if not on that first man page I tried, in a meaningful see-also page.
These days, seems most software (not just Linux, but for any platform) is scattered amongst HTML-urls that point to long-gone former websites, and youtube tutorial videos.
Now you might say that much of today's software is too complex to describe in a man page --- but IMHO - that's the bigger problem. If people write complex monolithic bloat, writing pretty documentation for it is the least of our problems.