All on one page
When designing a piece of documentation, should we aim for one long page or many shorter pages?
Heh heh, I know, this is akin to asking whether a long piece of string is better than a short one. In the case of documentation, the answer depends very much on the subject matter, the output medium and the audience. So let’s aim for that amorphous but well known category “online documentation”.
Setting the scene
Until a couple of years ago, I was totally convinced of the value of short pages. I designed multi-layered documents, branching down into nicely categorised, easily digestible chunks of information.
“Don’t scare off your reader by cramming too much information into one page.”
Then I started working on a wiki, where readers have an easy way of communicating their opinion of the documentation we write. To my surprise, I found a number of comments from readers expressing frustration that they had to keep drilling down to get to the information they needed.
The most common request was to have the information “all on one page“. This was especially true of our installation guides. Many people hate having links all over the page, because they don’t know whether or not they need to click a particular link, since they can’t see what it’s going to tell them. Even if the writer introduces the link with “Read xxx to find out more about yyyy”, that is still not the same as being able to run your eye over the content and read or ignore it at will.
From talking to developers at the company where I work, I’ve discovered that most of them prefer having the information “all on one page” too.
Another relevant point is that we often don’t know what platform our readers are using. This is especially true when the documentation is online. Not so long ago, we could optimise our pages for 800×600 and be sure that we’d be serving most readers well. Soon 1024×768 was all the rage. But now, people are reading the same pages on their mega screens at work, then later on their laptop screens at home, and occasionally on their iPhones or other mobile devices while sitting on the bus or hanging from a cable car.
Other people are not using a screen at all, but a braille reader or a text-to-voice translator.
Simple HTML and web browser rendering are ideal for this situation. They allow the text to flow into the space provided by our readers’ devices. In fact, you could say that we would be doing our readers a disservice if we tried to force the content into one particular page format or length.
Having everything on one page improves your search results too. People will receive fewer matches to their search requests and will find the information more easily (provided they can search the content of the page once it’s loaded).
What happens if your page has a lot of pictures or other things that make it load slowly? Would this be a good reason for breaking the information up into smaller chunks? Probably not, these days. Many of our readers are on super fast connections. And most web browsers do a good job of loading the text first, so that you can read the whole page while waiting for the pictures.
How I’m writing now
My pages are tending to be longer than they were two years ago. They hold more information.
At the top of the page it’s useful to have a mini table of contents, in the form of a hyperlinked list of the headings on the page.
Within the page, I use headings and other forms of highlighting that help people to skim over the content and alight on the paragraph they need.
Here’s a link to an example page. The page tells developers how to create an XML file describing a plugin. The page contains a short introduction, an example of the XML file, and a description of each element in the XML file. We could split this page into three separate pages, one for each section just described. We could even split it into separate pages for each XML element.
Conversely, we could merge that page and all its sibling pages into the parent page (“Plugin Framework Development Hub”) and have one humongous long developer document.
“You wanted it all on one page? Try this for size!”😉
Nah, that’s going too far. The design job of splitting the information into logical chunks is still very important. But those chunks are a bit bigger than they were before.
If you’re working in an environment that uses single sourcing and content re-use, so much the better. Then you still have the fun of creating those nice neat bits, and you can just spew out the long page when the content is destined for an online environment.
How are you doing it these days?
OK, now it’s your turn. Shoot me down🙂
But before you do, here’s a tantaliser for those who think chocolate and technical writing go hand in hand.
One big piece of chocolate or many small pieces?
At least here the choice here is easy: All of it🙂