Online documentation: what's missing

by Andy Oram

For several years I've been fascinated with technical information people get online, instead of from books or journals. Everybody looks online for help installing software, finding programming library calls, fixing bugs, and solving any other technical problem they have on their systems. (Systems, not computers--computers are boring, Steve Jobs told us that. Nobody wants to be associated with computers any more.)

A lot of information is still missing online. That's good for O'Reilly, because it means the book industry still plays an important role. But this article is not about missing information in general. It's about a specific segment of missing information: the frustration you feel when you visit a site and don't understand it because it lacks some background you need.

I encountered innumerable background issues while coding up some JavaScript recently. For instance, after cloning a large and complex node, I was stymied for a long time because I tried to alter children of the node and kept being told they didn't exist. It was a surprise to find, ultimately, that white space between nested elements counts as a child node. (The log call in Firebug helped a lot to clear up the mystery.) This is just one example where a reader needs to bring his own background to online documentation.


Nick Dixon
2007-01-16 04:09:56
This is what's wrong with Wikipedia: the editors and authors of traditional encyclopedias know their audience, and it's usually the layman. In Wikipedia. many articles are written for a reader who already knows the subject very well, and are therefore impenetrable for a newcomer wanting to learn.

This makes wikipedia a useful reference, but a fairly useless tutorial.
Try this: pick a technnical subject you're interested in but don't know much about, and look it up in Wikipedia. Then read about the same thing on Marshall Brain's HowStuffWorks.

Then ask yourself: from which did you learn most? And which was better written?
Articles like those written by Marshall Brain make Wikipedia look like so many college students trying to impress their class-mates and score points from their tutor, like some kind of undergrad buzzword bingo.

Consider this gem from the Wiipedia page on Hydrogen:

The large amount of neutral hydrogen found in the damped Lyman-alpha systems is thought to dominate the cosmological baryonic density of the Universe up to redshift z=4.


Buzzword Bingo.

2007-01-16 04:37:06
Aye, aye, aye.

But isn't Google for locating the background info? Or the nearest search bar?
Yeah, but they still fail in a way.

Anthony Cowley
2007-01-16 10:56:44
The issue you identify is very real, but I fear that your proposed solution flies in the face of the spirit of the phenomenon you are trying to improve. Much of the information you describe (the informal tutorials, for example) are hastily written by someone who managed to solve a particular problem. Such writing has all the deficiencies you mention, but the very existence of that document on the web is a direct consequence of the act of publishing requiring virtually zero effort.

Anyone with a web page, blogs in particular, can very easily throw together an article that will be accessible to the world. The motivation for doing this is often altruistic, but also not very powerful. The action itself is usually only carried out because it is so easy, and the author feels no responsibility about any aspect of what they are publishing. To require authors to review additions submitted by readers completely changes the nature of publishing an informal how-to on the web.

In fact, the technology to address this very issue is already here: the wiki. I won't belabor the analysis of wiki technology here, but suffice to say that wiki technology is an attempt to address just what you bring up.

Ultimately, I feel that we will muddle along with fragmented how-tos and tutorials scattered around the web. To ask more of the author leads one to the question: would you rather have scattered fragments or nothing at all? I think we would all rather have something than nothing, even if that something can often cause trouble. I would also like to point out that chasing down the background information you need is a wonderful process of personalization that would be hard to capture with a traditional reference. Semantic web folks are surely wincing at our naiveté in these matters, and it does seem to me that automated search assistants are the way forward in this area.

Saqib Ali
2007-01-16 19:02:34
Interesting Observation. Indeed. I used to run into this issue all the time. Reading a document, and suddenly I would drift into some incomprehensible section, mostly due to lack of background knowledge on my own part.

But Firefox has alleviated this inconvenience. Every time I drift over to the dark side, I select (highlight) the keywords from the section, right click and do a Search Google for "......". And right then and there I am one step closer to deciphering the message in the blurb.

I used this technique when I was writing my first ever ASP.NET in fact first ever .NET application. All the ASP.NET related material on the web (including MS MSDN site) assumes that you have already mastered .NET before coming to the world of ASP.NET. This certainly wasn't the case for me. I have a background in 3D programming using C, but never had touched .NET in my life. ASP.NET online documentation didn't help either. I found myself using the Firefox's inline search every few minutes. e.g. to use system.directoryservices library you have to first modify web.conf to add an assembly link to the DLL (who would have thought of that?). This was never stated in any document I found related to ASP.NET. I found the answer by following the google results into a USENET (yes it still exists) posting.

I think, the "collaborative background" idea is excellent. And it would have certainly helped me in finding the right assembly configuration for my web.config ;-)

2007-01-18 08:37:52
The ability to add annotations to online documents helps a great deal in this regard, and I'd like to see it used more often. CPAN uses this for perl module documentation. So if there's ever a typo, or error, or portion that's confusing, other people can add their own corrections, etc. The author never has to revise the original work, and people who access the document later benefit from the effort of those who came before.
Gautam Guliani
2007-01-22 19:22:25
Maybe the solution is wiki and Wiki Gardners
Andy Oram
2007-01-23 09:14:11
I'm delighted to get so many ideas in response to my small suggestion. In particular, WikiGardener looks valuable, but we should distinguish between two types of contribution, which are like the old metaphor of foxes and hedgehogs.

WikiGardeners can do a lot of superficial edits to multiple pages. I'd be a good WikiGardener, for instance, because I know enough to edit documents on many subjects but don't know enough on any one subject to write a lot.

On the other hands, some people are very knowledgeable in one narrow area; these are the types of people who are likely to be able to add links to web pages that point to good background documents.

I should also clarify what I'm looking for: not just tools, but structure. There are all kinds of promising tools for creating and editing documents. But to help people quickly find the information they need, we must impose structure as well. My simple idea for adding a link to a background document is an example of structure; the tools for implementing it would be trivial.

Mz K
2007-01-23 09:45:08
Happily, the PHP documentation website seems to address this rather well by letting readers submit additional information/comments. :)

I see your point but really most folks posting snippets of technical information probably only do this on an occasional basis, and, I'm guessing to help themselves as well as the known world. It's good you bring this to our attention, however. Frankly, I'm an impatient sort and often don't have the motivation to weed through books, even wonderfully written ones! Maybe Google will save us by coming up with some sort of TechnoPedia where folks can fill in prerequisites (point to reference sites) and then go on about the topic. The Web is continually involving in its usefulness and presentation.

2008-07-28 14:27:14

I know what you are getting at, and I think that it is going to take some time, but the wiki and blog go a long way to improving the situation. It will take time for people (and organizations) to digest the technology (look at how people are STILL learning to email and IM properly...), but at least there is a place to put stuff now.

Before there were blogs, I maintained a personal website and tried to put up articles on network troubleshooting. Lately I've been using someone's wiki engine, and I have a lot more time to focus on writing the key articles and gluing the context back together for an end user...

BTW, I've had the article writing style of having an abstract, audience, references, etc. sections in my documents. When I started doing that, I felt awkward, but over the years, nobody seemed to complain (maybe because I was often the only person doing the writing...)

I think that helps a lot, because you can go back, and look at the article and say: "was this really for end users?" "does this reference really help explain what I talked about?"