Things People Hate about Your Open Source Docs

If HN allowed signatures, that quote would be mine. I grok libraries and other people's code so much faster when I have a good working example, and the mere existence of that example makes me 10x more likely to use the lib (or, when I have no other option, 10x more likely to complain less).

I write this up to GNU's "info" being preferred by some programs, but then that not being installed properly or at all on many system, and people hating manpage syntax, often with good reason.

That said, some systems pay a lot of attention to this. OpenBSD's mandoc is a great example of a modernization of the manpage system, and their manpages are second to none: http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html

I've had people complain to me that no one is using their great open source project. I complain that you don't explain what it does or why its great.

They answer that all you have to do is read the code. I try to diplomatically tell them that there aren't enough hours in anyone's life to read all the code on Github.

The project is not ready to upload if you haven't finished the documentation.

I've worked on at least a couple of open source projects now that have a strong and active core team building everything, and who are talented enough to write great code. But when it's almost time to launch v1.0, the call always goes around: "Who's willing to write the documentation?" And the response is always silence. Documenting just isn't as "fun" as coding, I guess.

But it is, arguably, at least as important if not more, if your goal involves popularity. I recommend open source software projects to groups who are looking for an open source solution, and the ones with an active support community and good documentation, but some sloppy code, win every time over the expertly coded masterpiece that can only really be understood by stepping through the code in a debugger.

For example, see Django vs. Turbogears or Pylons.

Documentation matters, a lot, despite its relative unsexyness.

Good "feature list" would probably help, but it's just a pain when reading through 5 paragraphs down only to find that it's not what I think it is.

So true.

I've frequently had the impression that writers are plain missing the point - with the most dense, clever self-satisfying examples as opposed to verbose, simple and instructive.

So many GUI libraries do this and it's always frustrating. If you're a GUI library, when I get to your website, the first thing I see should be a screenshot.

As @coherentpony stated, at least with open source others can pick up the slack.

There's a joke to the effect of "Every working Unix program derives from 'Hello, world!' in K&R." There's a similar joke about Windows programs and the first example program in Petzold's book. Write your library or tool's version of a 'Hello, world!', make it tasteful, and keep it working across bug fixes and version changes. That's the testbed; that's what people new to your work will modify stepwise into whatever they really want to build.

The second thing I wish I saw more often are "Theory Of Operation" documents, which document how the developers expect their stuff to be used.

Who is the intended audience? What other stuff do the developers expect the intended audience has seen? If it's a library, what do the developers expect the core of a client application to look like? If it's a tool, what do the developers expect its most common mode of interaction to be? It shouldn't be a listing of what each function does, but something that gives an idea of what the developers think the core functionality is would be very helpful.

Get into the head of your users. What would you want to know going in, if you were a user?