Of course, your examples shouldn’t just be brief two-line snippets. As Rich Bowen of the Apache project puts it, “One correct, functional, tested, commented example trumps a page of prose, every time.”
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).
This is 100% true. I am constantly frustrated by incomplete code examples in documentation. The one thing in particular that bothers me the most are when Python snippets don't show the import statements.
The Three.js project has really shit documentation for most things, but they have scrupulously-maintained examples for their library which serve to answer most questions.
Manpages used to be the defacto best source of information, but sometime in the last 15 years they went from great to a hit and miss shambles.
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.
I think people now like documentation in lots of different forms - manpages, HTML, pdf, or introspectable docs like Python docstrings. IPython, for example, has all four of those.
There are systems like Sphinx that let you share content between different formats, but they're not magic bullets. For instance, if I write docs relying on inline links because I'm used to viewing them in HTML, the result won't be great for manpage readers.
to get the content with a more (or less) familiar nav tool.
Another useful approach is to 'project the document' rather than to
'document the project'. Write the draft documents as part of the
specification and development process. Code the project. Finally,
edit the docs to match the code.
You get to capture the state of early energy and an over- or
top-down view before diving into the code, and will remember to
mention details of the design while they are fresh and new, rather
than at the end of the coding process, when everything has become so
familiar that it all seems trivially obvious.
I think I've seen every imaginable "bar" object have every possible "foo" action performed on it. This is the most frustrating thing I find in example code. Yes, I know your library is generalized and will work with any type of object. Please give me a concrete example of where your library might be useful, so I can easily visualize your library's role in my head. I can generalize it myself, thank you very much.
I hate incomplete docs the most. Most OSS developers would agree that if you're adding a feature to a repository, then you should also be adding a test. There should also be an expectation that you should be adding docs, too.
Having offline docs can be quite handy. A few years ago a friend and I put together an iOS app called iCPAN, so that we could have offline Perl docs at our disposal. This kind of thing is particularly helpful because perldoc doesn't work on modules which you have not yet installed. It's also great if you want to read Perl docs on the subway, but I'll admit that's not everyone's cup of tea. :)
The biggest sin is not explaining what the project does and the problem that it solves.
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.
It's occurred to individuals smarter than myself that projects rise and fall on the strength of their documentation, almost as much as that of their code.
For example, see Django vs. Turbogears or Pylons.
Documentation matters, a lot, despite its relative unsexyness.
The great thing about open source documentation is that you can write a patch and attempt to fix it. It would probably take less time to clone a repository and submit a pull request than it did for the author to write that article.
Yes, instead of writing an excellent article that explains some principles that could help hundreds or thousands of open source authors improve their projects, he should have taken the approach of shutting up and fixing every one of those projects himself.
Open source should not be about efficiency! It should be about never pointing out anything wrong unless you're willing to change it yourself! Down with feedback! We hate feedback! We're open source authors and we don't have to take it anymore!
Lack of examples is the major problem, since it is hard to maintain examples in sync with the code. I created tool https://npmjs.org/package/xplain that transforms unit tests (javascript) into human readable examples in the API docs. Makes lots of up-to-date examples in the docs possible without any penalty.
Not necessary docs, but what I have been observing in a lot of OSS is an absence of one-liner explaining what the project exactly is; especially ones without descriptive project name.
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.
I like to create README files that are also shell scripts that perform some of the actions the README says you need to do to build/run whatever it is I'm writing about.
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.
The biggest thing I'd like to see more often are usable example applications. Not just snippets of example code, but working applications which show off some aspect of what your library or tool is intended to do in a complete form. And keep in mind that people looking to see if they want to use your stuff see buggy applications, that reflects on everything.
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?
[+] [-] cobrausn|12 years ago|reply
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).
[+] [-] Apreche|12 years ago|reply
do_magic(param, other_param)
Where do I import do_magic from?!?!
[+] [-] angersock|12 years ago|reply
[+] [-] zdw|12 years ago|reply
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
[+] [-] takluyver|12 years ago|reply
There are systems like Sphinx that let you share content between different formats, but they're not magic bullets. For instance, if I write docs relying on inline links because I'm used to viewing them in HTML, the result won't be great for manpage readers.
[+] [-] dmckeon|12 years ago|reply
Another useful approach is to 'project the document' rather than to 'document the project'. Write the draft documents as part of the specification and development process. Code the project. Finally, edit the docs to match the code.
You get to capture the state of early energy and an over- or top-down view before diving into the code, and will remember to mention details of the design while they are fresh and new, rather than at the end of the coding process, when everything has become so familiar that it all seems trivially obvious.
[+] [-] kyrias|12 years ago|reply
[+] [-] coldpie|12 years ago|reply
[+] [-] vacri|12 years ago|reply
[+] [-] psychometry|12 years ago|reply
[+] [-] oalders|12 years ago|reply
[+] [-] SubMachinePun|12 years ago|reply
[+] [-] rmason|12 years ago|reply
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.
[+] [-] duwease|12 years ago|reply
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.
[+] [-] doktrin|12 years ago|reply
For example, see Django vs. Turbogears or Pylons.
Documentation matters, a lot, despite its relative unsexyness.
[+] [-] coherentpony|12 years ago|reply
[+] [-] hamburglar|12 years ago|reply
Open source should not be about efficiency! It should be about never pointing out anything wrong unless you're willing to change it yourself! Down with feedback! We hate feedback! We're open source authors and we don't have to take it anymore!
[+] [-] gleb_bahmutov|12 years ago|reply
[+] [-] unsignedint|12 years ago|reply
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.
[+] [-] daemonl|12 years ago|reply
[+] [-] lignuist|12 years ago|reply
[+] [-] Nursie|12 years ago|reply
[+] [-] beat|12 years ago|reply
[+] [-] incision|12 years ago|reply
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.
[+] [-] egonschiele|12 years ago|reply
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.
[+] [-] yaddayadda|12 years ago|reply
As @coherentpony stated, at least with open source others can pick up the slack.
[+] [-] derleth|12 years ago|reply
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?