A wiki is not a replacement for real documentation
Note: The latest version of this document can be found here
For those interested in the documentation tweet (http://twitter.com/febuiles/status/4892316133):
For the purpose of this discussion, I’ll divide documentation in two categories:
- Guides
- Reference
They serve different purposes, a guide is supposed to take you through a piece of software and all its capabilities, usually with examples and detailed explanations.
Reference guides usually serve the experienced programmers find what they’re looking for. They’re not interested in all the verbose text around a function explaining how it came to life, they just want a short overview of what it does and maybe an example.
The Guides
Rails Guides (http://guides.rubyonrails.org/) are a great example of what a guide should have, lets take the Migrations guide (http://guides.rubyonrails.org/migrations.html). You get the chapters list (table of contents) on the right so you can jump to any section you need, you get an explanation of what a migration is near the top (in case you don’t know if that’s exactly what you’re looking for), you get a “Here, this is what you’ll learn today” paragraph so you can see if something’s relevant for you, and then you get a book-quality guide with code examples and tips (both are obvious to the reader, in different colors and in their own boxes). And the best part of it? Everything’s in one page, if you want to find something you’re one Cmd-F away from finding it. If you can’t learn what a migration is after reading that document you should just stop developing web apps (with Rails) and go raise pigs (I’ve heard it’s a nice profession with great bonuses and a lot of useful real life experience).
On the other hand, you can also get stuff like SproutCore’s website (http://www.sproutcore.com/). If you’re like me and you wanna see what Javascript frameworks are up to you’d go click on the “Learn More” link in the bottom to go taken to their wiki and there, after trying to visually parse a thousand links you’ll find the “SproutCore Basics” page (http://wiki.sproutcore.com/Basics-Introduction). You’ll see the 2 main problems with guides in that page so please pay attention:
See the “Older docs. Moving to a new guide or removing.” comment? Yeah, that happens, all the time. It’s a wiki and its distributed nature (pages everywhere, related together only by links[1]) hides the fact that some pages are out of date. Marking them as “Out of date” might help the users, but the developers might not notice it if they don’t usually go to that page.
And this is some serious shit. Notice how the outline is divided in 4 sections? Ok, that’s good, now, try to find the “Next” button. Go ahead, I’ll wait for you here.
Oh, you didn’t find it? Neither did I, don’t worry. Go ahead and click on (1) Introducing SproutCore.
You take your time, read through the whole thing and then realize that HTML5 will save the universe, great. Now, how do I move to section 2?
Oh right, this is a wiki, there’s no sequential structure or anything like that, this is just a collection of documents. And here lies the problem with this system, it might work for documents with 4 sections (it’s only pressing backspace four times and then clicking another four, not that bad), but what happens when your piece of software has hundreds or thousands of pages (see Emacs: http://www.cs.cmu.edu/cgi-bin/info2www?(emacs)Top) ?
Good luck trying to find how to configure your OpenVPN through the US gateway in OS X (http://wiki.witopia.net/wiki/Main_Page).
The References
As said above, the reference guides are usually a bunch of APIs documented in the same place with short overviews of what something does and maybe an example of the thing at work. A great example of a reference guide is the RDoc documentation for Ruby (http://www.ruby-doc.org/core/) [2]. If you know what you’re looking for you’re one Cmd-F away from finding it (again integrated browser search, start to notice a pattern?).
The thing with references is that sometimes you will be looking for a lot of stuff instead of looking for a specific fact (how do I convert an ASCII string to Unicode in Python? Let’s take a lookt at str). This makes having all the information in a concise format in the same page a gift from the gods.
Python is pretty good known for having this terrible documentation which tries too hard to be a reference and a guide at the same time. Google for “python string” and the first result you’ll get is “Built-in Types”, a page that not only describes strings but also describes lists, tuples, floats and more. It’s as verbose as it gets and it’s missing critical stuff like a way to easily move between the methods, but it’s still better than a wiki becase you know that all the information is there, on that page.
There’s one more issue with wikis and that’s keeping them updated. A reference like the RDoc one is easily updated every time you updated the code because it’s kept there in the same place as the source code. With a wiki you might bet a bit lazy and tell yourself that you’ll update it as soon as the 30000 RSpec expectations finish running. While they execute you’ll go for a coffee and meet a pretty nice waitress at the cafeteria, you’ll talk to her for a while and boom, there goes the updated documentation.
Conclusion
I hope this helped clarify my frustration with Wiki documentation (I blame OpenSocial). If you have any questions, suggestions or criticism you can reach me at federico.builes@gmail.com
[1] Wiki systems usually have to fix this when they “reach critical mass”, search for any entry on a person’s life, a country or a virus in Wikipedia and you’ll find a bunch of [nice] chrome on the right side and on the bottom with a lot of useful information like the facts for a category in the right (area, population, GDP. and more when you’re looking for a country) or the topics in the bottom (history, geography, government). This kind of structured approach is usually frowned upon by Wiki proponents but even they realize it’s the only way to categorize a lot of information.
[2] It’s great in the sense that it’s easy to use and serves its purpose just right. The quality of the documentation itself could be a bit better.
[3] Another option proposed by @diegoeche in Twitter is using literal programming (Knuth’s idea for software). It might be worth checking it out.
