Looking for great examples of organizing developer documentation

May 25, 2010 10:47 PM

Which software projects' Web sites stand out as having really well-organized documentation?

I work on an open source project which struggles to make up-to-date documentation easily accessible to developers of all skill levels. We're talking about redesigning our Web site and I'd love to see some examples of large projects (open source or commercial) that really excel in this area.

To be clear, I'm not looking for advice on writing documentation or which CMS to use, just examples so I can see how others organize documentation that developers can find it easily.

posted by tomwheeler to computers & internet (17 answers total)

Open Source sites I love when developing/administrating:

- Apache HTTPD: I can list either by directive, or by which module I'm interested in.

- Anything Javadoc, as long as it is well maintained. The language library is pretty good. I can go exactly where I need to to get the documentation on the class/method I'm interested in. Package docs have a nice overview. Class docs often contain a large header with extended information. Inherited methods/variables are listed and where they come from.

- CPAN: the search almost always brings me what I want. For every module I can see the POD or even switch over to the source. And big ++ is that I can select the version I want to see (as long as the author doesn't change)

- PHP: search works reasonably well, and the function reference is usually pretty handy. I've always got a couple tabs open for quick lookup of a function or module

Sites I don't like:

- Anything wiki. Stuff is always missing. Docs are always marked as OUTDATED (not helpful, thanks). Pages have varying standards and aren't well organized.

- Rubydoc. I often have a hard time navigating where I need to be and figuring out which module/mixin/superclass contains what it is I'm looking for. It's just to sparse for how I use it.

- The W3C. Uggg... do I even need to get started on this one?
posted by sbutler at 11:02 PM on May 25, 2010

I think I'm just repeating sbutler, but...

Every Wiki based documentation I've seen has been a complete waste. Invariable it's linked to missing pages, circular linking, etc. And the content that exists is often for different versions, hilariously incomplete, or in some cases vandalized.

I've always liked PHP's documentation. It's clear, easily searchable, and the users have often contributed really useful insight and code snippets. It's also available in a number of offline formats.

Javadoc is nice and clean if done right. Most people are used to formatting for it and navigating it. And if they're not, its easy to get the hang of it.
posted by Ookseer at 11:33 PM on May 25, 2010

Qt's developer documentation is fantastic.
posted by cmonkey at 11:42 PM on May 25, 2010

I really like python's documentation, especially since it can be downloaded in a variety of formats (including Windows' compiled help media).
posted by mnemonic at 11:43 PM on May 25, 2010

I think php.net is pretty much perfect.

Aspects that I like:

• Search on function name - if it doesn't find what you're looking for it has a bunch of suggestions so if you dont know the whole function name you can just put in a fragment and it will probably find it
• Related functions - if a function does something close to what you're trying to do, you'll often find there's a function listed in the related functions that does exactly what you want :)
• Functions organised by topic for easy browsing - if you don't know the name of a function (or if it even exists) and its not similar enough to a function you do know to be in the related function section you can browse through all the functions on that theme - eg if you want to manipulate a string and the only string function you know is strlen, if you go to its function page, all the string functions are listed on the left
• Code samples - sometimes an example is so much clearer than an explanation and php.net usually includes at least a couple of examples of its use along with the expected output/result
• User submitted code examples and comments - the code examples are usually more extensive and practical than the ones given in the main docs (which are really basic just to illustrate usage), you'll often find someone has tried to do what you were trying to do and has left an example of how they did it

posted by missmagenta at 11:48 PM on May 25, 2010

I also am a big fan of the python documentation.
posted by curious_yellow at 12:20 AM on May 26, 2010

perldoc helps me in a pinch - faster in the browser than in TextMate - usually you can just pop,

perldoc whatever

in your address bar and google will do the rest,


As a writer of online docs for nerd apps, it is not such an easy task. Especially when the target is always frickin' moving.
posted by alex_skazat at 1:01 AM on May 26, 2010

Javadoc is excellent if you know what you're looking for; I have a search shortcut set up so I can type 'jd arrayblockingqueue' and get taken to the right documentation immediately.

However, when you're a new developer, just getting dropped off at a page like this makes it difficult to know where to start - as you probably don't even know what an ArrayBlockingQueue is! Sun also provides some getting started tutorials covering the basics of key technologies, which address this.

I work on an open source project which struggles to make up-to-date documentation easily accessible to developers of all skill levels.

The other thing that Java does well is basic documentation doesn't go out of date much, because major releases are infrequent and do not break backwards compatibility. In other words, introductory documents for Java 6 will also work with Java 7 because they aren't going to break how 'Hello World' works between versions.

Compare that to Facebook's API which has several different sets of documentation for different APIs (some deprecated and others missing capabilities from old APIs) code examples that no longer work, libraries with disappearing functions, and so on. You get a developer key and the signup website presents you with a code example and an URL to a library, you download both, and the example code doesn't work because it calls library functions which no longer exist.

That's not to say that Java never changes - new features are often added, and tutorials go out of date if the technologies they run on get replaced - but for the most part even code examples from years ago will still compile and run just fine.
posted by Mike1024 at 1:30 AM on May 26, 2010

If I could suggest a bit of clarification: While it's not required that you tell what the project is, you've left it a bit ambiguous what a "developer" is your context. It might be a good idea to at least explain a little about who'll be reading these docs.

Right now, the responses are pretty much all projects that are entirely code-based, which is fine if that's your case, but if your project involves an actual application with a front end that people have to be taught how to get around, etc., there's an entire aspect currently being largely ignored.

As far as what's known now, I've generally found the jQuery docs pleasant to use and easy to get around once I got a feel for the basic organization(selectors, traversion, etc.) In particular, the extended example snippets are nicely atomic, usually doing only just enough to get the information across. I've often found that many projects either throw you nothing but a pseudo-code syntax example like "jQuery('[attribute|=value]')" and expect you to know what to do with it(fine for the already-experienced), or that the examples do too much and then make you dig for the bit you were actually looking up.
posted by Su at 2:35 AM on May 26, 2010

When it comes to content quality, my favorite is FreeBSD. Its handbook and manual pages especially stand out in terms of clarity, accuracy, up-to-dateness and completeness.
posted by knz at 3:01 AM on May 26, 2010

Django's documentation is presented well, comprehensive, and readable for non-experts.
posted by jzed at 5:31 AM on May 26, 2010

CodeIgniter and ExpressionEngine (from the same company) have good documentation. They're supplemented by user forums and wikis, which is nice, but they could be integrated better.
posted by kirkaracha at 6:29 AM on May 26, 2010

2nd Django documentation. Very comprehensive, links to sections on the right side is very helpful, but most importantly, every single concept that may be hard to grasp is followed by a clear example.

I like Python's documentation too, and Python's library is many times bigger than DJango but many topics could use examples.
posted by rainy at 7:23 AM on May 26, 2010

I am going to go against the grain and say that, while I think the Python documentation is well-organized, it is not particularly helpful for new users. Much of the documentation seems to be between describing an API (these functions exist) and an actual language specification (this is what this function call does), rather than describing simple task flow (this is how you use this module if you want to do x) or basic idioms (for those of you from C, here is how we do our loops in Python).
posted by adipocere at 7:50 AM on May 26, 2010

Seconding Django. I spotted the project shortly after their first public release, and one of the things that really stood out was the quality of the documentation and tutorials.

You might check out PostgresSQL too. I don't know how the documentation is for people looking to contribute code to the project, but the documentation for admins and DB developers is pretty thorough and clear.
posted by Good Brain at 11:13 AM on May 26, 2010

Nthing Django. It has really incredible documentation which, in addition to an awesome community, made it a pleasure to learn.
posted by i_am_a_Jedi at 4:22 PM on May 26, 2010

I'm a little late to the thread here, but had to mention the FreeBSD project's Handbook.
posted by dirm at 7:10 PM on May 26, 2010