Forgot your password?
typodupeerror
Open Source Programming Linux

Ask Slashdot: What To Do About the Sorry State of FOSS Documentation? 430

Posted by samzenpus
from the keeping-up-with-the-times dept.
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?
This discussion has been archived. No new comments can be posted.

Ask Slashdot: What To Do About the Sorry State of FOSS Documentation?

Comments Filter:
  • by Anonymous Coward on Monday August 04, 2014 @11:13AM (#47599781)

    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.

    • I would say Solaris has always had the best documentation... Until oracle at least.
    • Re: (Score:3, Insightful)

      by Anonymous Coward

      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.

    • 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.

      • by Graymalkin (13732) * on Monday August 04, 2014 @05:33PM (#47602783)

        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.

        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.

  • Real men (Score:4, Insightful)

    by Raseri (812266) on Monday August 04, 2014 @11:16AM (#47599807)
    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.
  • Hire someone who knows the product (a starving developer?) to help you.
  • So fix it (Score:2, Interesting)

    by Anonymous Coward

    I document my findings on the Ubuntu wiki. If more people would take the hour to write up details on what they spent 2 weeks learning, we would all be better off for it.

    • Or, for the less altruistic out there, write tutorials, put them on your own blog and youtube, link them from the project's wiki in a reasonable, completely non-spammy way (e.g. copy the content, attribute it to your blog with a clearly marked external link), and make a dollar or two from advertising.

      Or, if you have the money to spend, offer a bounty [bountysource.com].

  • by jellomizer (103300) on Monday August 04, 2014 @11:20AM (#47599859)

    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.

    • by Ghostworks (991012) on Monday August 04, 2014 @11:36AM (#47600025)

      "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.

      • by gfxguy (98788)

        I would think there should be automated ways to generate documentation based on the specifications and requirements.

        For example, if you're using an "agile" approach, and have your list of stories that need to be addressed, and the developers then create a list of tasks in order to address those stories, the tasks should have enough information to describe what they're doing.... not necessarily implementation details, but if they're writing a function for example, it should document what gets passed in and

        • by jbolden (176878)

          Agile stories don't make great documentation because of their focus.

          Story 1: Enters a transaction in a state which doesn't have county level sales taxes.
          Story 2: Enters a transaction in a state which does have county level sales taxes but neither the county nor municipality impose one.
          Story 3: Enters a transaction in a state which does have county level sales taxes the muncipality imposes one but the country does not.

          etc...

          Mattes a great deal to the software but you are exposing the abstraction. The end

        • The stories would be of the form:

          As a user, I want to change my password...

          But they generally won't say that the means to do that should be a link from the user account page or what the steps of the process would be. Now for something simple like a a password change, there are generally well defined industry best practices that both the developer and the end user are probably aware of and so both have a common conception of what should happen. That isn't true for functions specific to the application or d

        • ... generate documentation based on the specifications and requirements.

          What are these strange and mystic words you use?

    • by Livius (318358)

      But the documentation if complete would probably be just as large if not larger then the code, and just as complex to read.

      If that's what it takes, then so be it.

    • There are three basic levels (bunch of gray in between): Basic, Intermediate and Advanced.

      Basic usage (80%) can be simple easy to follow instructions. The next 15% is Intermediate use, which requires Proficiency at Basic Level, followed by Advanced, which requires proficiency at Intermediate levels.

      Most documentation is designed for Intermediate/Advanced users OR basic only.

    • by dskoll (99328) on Monday August 04, 2014 @11:56AM (#47600209)

      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.

  • by Anonymous Coward

    In the past, there was usually a fairly good set of manual pages that seemed to accompany most OSS projects. However, nowdays all huge portion of projects seem to just think that if they set up a documenation wiki, they don't need to do anything else and some awesome documentation will just appear.

  • Yes! (Score:5, Interesting)

    by war4peace (1628283) on Monday August 04, 2014 @11:22AM (#47599881)

    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.

    • 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.

      I do wonder which projects. My experience has been the opposite: providing detailed information and reasonable evidence that I'd read the document has always produced helpful, thoughtful responses (even from Theo de Raadt himself).

      Have you been asking the original developers or on various forums?

    • by gfxguy (98788)
      Where've you been looking? The Ubuntu forums are generally not bad at all, and in my experience have been very user friendly. I've been using Linux for quite some time; I'm a developer, but don't think everybody should have to be a system administrator in order to use Linux as their desktop. I don't know everything... I write graphics applications. If my network or sound card isn't working, I have just as much of a problem as most newbies.
      • by mvdwege (243851)

        The Ubuntu forums overflow with very friendly idiots who cannot do anything but post "I have the same issue", or cargo cult solutions that are out of date.

  • If the webpage for your application consists entirely of a long list of bug fixes, you're dong it wrong. This is why you need more than a programmer to make a real application. A technical writer and even a [GASP] actual UI designer can take you from amateur hour to prime time.

  • by Dimwit (36756) on Monday August 04, 2014 @11:26AM (#47599913)

    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.

  • Some years back I decided to play around with FVWM. I was astounded with quality the man pages. FVWM isn't so much a window manager as it is a window manager *kit*, with lots & lots of configuration options. But the documentation is some of the best I've seen.

    I've just been trying to work with lightdm here, myself (disable guest login & not auto-fill-in the last user name) and found the same as you. The config files have even been moved and no-one bothered to mention that.

    Anyway, I usually end up in

    • The config files have even been moved and no-one bothered to mention that.

      I've had to break strace out a few times before to figure out how to even begin configuring some tools, just to figure out where the heck it's trying to read stuff from.

  • by DarkOx (621550) on Monday August 04, 2014 @11:31AM (#47599981) Journal

    I bet most projects would be happy to accept patches to their man pages, and files they store in /usr/doc/ if they improve quality or accuracy.

    This is one of the few areas where just about anyone can contribute even if you don't code. Chances are you can still read it enough glean what the expected options are etc.

    • I bet most projects would be happy to accept patches to their man pages, and files they store in /usr/doc/ if they improve quality or accuracy.

      What you say is quite true however it doesn't really get at the root of the problem. If I ever have to consult a man page and I'm not doing something really arcane then the application interface is badly designed. No amount of documentation will ever fix a bad interface.

  • ARCH LINUX WIKI (Score:5, Informative)

    by hduff (570443) <<moc.liamg> <ta> <ffudtyoh>> on Monday August 04, 2014 @11:33AM (#47599999) Homepage Journal

    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.

  • Corrected Title (Score:5, Insightful)

    by harl (84412) on Monday August 04, 2014 @11:34AM (#47600015)
    Ask Slashdot: What To Do About the Sorry State of All Software Documentation Everywhere?
  • For YEARS there's a been a file named INSTALL_SOURCE or something like it. Indeed, there's a section on that, but a lot of the file is how to download and install precompiled binaries. It's a little thing, but it just bugs me ever time I have to skip past the stuff that shouldn't be in there to get the stuff that should.

  • For a product intended for use by non-techies, LibreOffice's end user documentation is horrible. It's uneven in coverage, lacks useful examples, and is generally not sufficiently detailed. Comparing MS Office's documentation to LIbreOffice's documentation should make this obvious to all involved in LibreOffice even if they, themselves, are not "non-techie end users" and think "just read the code" is a good answer. This lacking reduces the uptake of LibreOffice unfortunately.

    Interestingly, the fact that MS O

  • by Bob9113 (14996) on Monday August 04, 2014 @11:48AM (#47600141) Homepage

    How about crowdfunding some documentation efforts by real technical writers?

    The reality, for better or worse, is that writing FLOSS code has sufficient apparent benefits for the software engineers and their sponsors to get the job done. The technical writing of good documentation does not. Whatever the reasons, it is the case; that has been the reality for decades.

    But how much would it cost for a first pass at documentation? Take "Installing and Configuring MyCloud" as the example. Contact a few people who have written articles or put up YouTube videos on the subject. Let's get a high estimate; call it $100/hr, one month, three documenters, 10 hours per week each, 50% overhead = $100 * 1 * 3 * (4 * 10) * 1.5 = $18,000.

    That seems do-able, and a good opportunity to develop a crowdfunded brand; a team that grows a reputation for getting projects done. Then you could offer a follow-on project to do a deeper dive on the same subject, or put together another team to do Asterisk & Secure VoIP, or whatever is next. Maybe start with the counter-NSA stuff, where there's a sudden broad interest and complex software that, until now, has been run mostly by experts.

    A few thousands of people willing to kick in a small amount of money each toward a common goal; crowdfunding documentation seems like a natural fit.

    • How about crowdfunding some documentation efforts by real technical writers?

      A band-aid that doesn't solve the real problem. Even if you did this and produced some great documentation, it would fairly rapidly become obsolete unless the software is never updated. You would have to basically create an endowment to fund ongoing documentation development. The real problem is that A) the interfaces are bad enough that documentation is even necessary in the first place and B) documentation is boring, unrewarding and time consuming to do well so nobody wants to bother.

  • by QuietLagoon (813062) on Monday August 04, 2014 @11:54AM (#47600195)
    The state of FOSS documentation is about the same or, in my experience, a bit better, than the state of software documentation in general.
  • Because they include documentation as one of their priorities.
  • I find FreeBSD typically has far better documentation than the various patchwork Linux distros. A lot of FOSS projects are actually quite well documented.

    The biggest problem with documentation is developers don't want to help maintain because it gets in the way of keeping their projects in a perpetual beta release state by changing things constantly.

    Stable and mature software that can be properly documented = stale software that's less interesting to developers.

  • Perhaps new contributors should start with the documentation, then "move up" to contributing code? Or would one more barrier to becoming a contributor merely make things worse?

  • by Enry (630) <enryNO@SPAMwayga.net> on Monday August 04, 2014 @12:12PM (#47600369) Journal

    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.

    • by Vellmont (569020)

      Coders are too busy writing code and making changes to what they write to give time for accurate documentation to be written....
      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.

      You've just described an extremely flawed development model. For some reason you can still get

  • by sjbe (173966) on Monday August 04, 2014 @12:18PM (#47600403)

    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.

  • by Kjella (173770) on Monday August 04, 2014 @12:24PM (#47600461) Homepage

    This exact story could have been posted the first day I visited /. and nothing has changed nor will it change. Keeping the documentation up to date with good examples is boring work and few want to do it. A lot of open source developers do it for their own benefit and will simply say that's not their problem. Since most of it is a volunteer effort you can't make them do anything and the few who want to write documentation can't make a dent in the number of changes that should have been documented.

    There are of course exceptions but they usually intersect with the kind of software that runs business critical applications where a lot of time and money is riding on it and paid developers do a lot of the work. Or you have someone who's being a bit of a nazi on it, but they tend to often get overrun by a fork that's moving more quick and dirty. Because users like to complain about poor documentation but they want the shiny new features too and there's not a few forks that's started because someone was rightly denied commit privileges.

    Personally I got tired of waiting for the gold at the end of the rainbow when things would finally stabilize and get working and documented and done. It is a half-baked work in progress and if you got the time and interest to deal with it please do. I managed to make Linux work for me for about 3.5 years, thinking I'd eventually get to stop tinkering with it but despite releases coming and going fixing some issues new ones appeared and it never really settled down. I finally decided to get a Win7 license four years ago, I guess Linux is an escape option if Microsoft doesn't clue in from Win8/8.1 but I don't expect much has changed.

    P.S. That's something I heard often, you tried like a 12 month old distro? Try it now, all your criticism is outdated and it's totally different and much better now. I used it long enough to know that's usually total BS.

  • by hughbar (579555) on Monday August 04, 2014 @12:27PM (#47600489) Homepage
    To blow my own tiny trumpet for a moment, I've written and updated a manual to go with: http://sourceforge.net/project... [sourceforge.net] for each release.

    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.
  • by SigmundFloyd (994648) on Monday August 04, 2014 @12:28PM (#47600497)

    I'm aghast at the state ofdocumentation for Open Source projects

    You must have missed OpenBSD [openbsd.org], then.
    I know, I know: It's an exception. I just wanted to mention the best documented Free Software I've ever seen.

  • I mail the author (Score:4, Interesting)

    by angel'o'sphere (80593) on Monday August 04, 2014 @12:30PM (#47600523) Homepage Journal

    Then I hire him, after all writing code I accidentally use in my commercial product, and feeling being hold hostage because in a corner area it does not work, is his business model :)

  • by Culture20 (968837) on Monday August 04, 2014 @12:40PM (#47600625)
    Switch all of the info docs back to man pages. man pages are neatly organized and have all of the info in a handy grep-able format. info help pages are as disorganized as 1990's websites with their random hyperlinking. Something GNU got waaay wrong.
  • by CanHasDIY (1672858) on Monday August 04, 2014 @12:48PM (#47600683) Homepage Journal

    ... 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.

  • by quintessentialk (926161) on Monday August 04, 2014 @12:54PM (#47600747)

    First, I wanted to link to This blog post [stevelosh.com] by Steve Losh on writing documentation. I think offers some good metaphors as to why 'reading the source', even 'self documenting' source, is insufficient, though of course not everyone will agree with his philosophy.

    Second, I wanted to say on the projects that I work on as a systems engineer doing new product development (as in this [wikipedia.org], not the information technology use of the term) documentation is perpetually threatened. And we usually work on comparatively well funded, non-FOSS programs. Documentation is timing consuming and expensive, and sometimes it is even customer direction to place it at a lower priority than new development. Though inevitably it makes things harder later, sometimes that is o.k. if it works better with the cash flow (saving money now only to pay more later can work if you expect to have more money later). Unfortunately FOSS software projects don't necessarily have people promising a ton of money for the documentation.

  • by GrumpySteen (1250194) on Monday August 04, 2014 @01:44PM (#47601131)

    Where do you go for your FOSS documentation and self-help?

    To be honest, my answer is often "closed source software from a company that provides documentation and support contacts."

    Yeah yeah... open source rah rah read the code and fix it yourself. Fuck that. I have better things to do with my time than trying to decipher and fix some other jackass's code.

"For the man who has everything... Penicillin." -- F. Borquin

Working...