Screencasts and Books: There's a Place for Both

Over on Steve Wilson's Virtual Steve blog, I commented on Steve's suggestion to Go Ahead! Put Yourself on YouTube. From the ensuing conversation, I realised that I should use my own blog to provide a more detailed response to some of the points raised.

So, here's the 12" remix of my comment to Steve. - I never knew there was so much on it

To borrow the catch phrase from an ancient TV commercial for the TV Times: - I never knew there was so much on it. Not only will you find information about How To Use LDAP Browser/Editor with OpenDS, but you'll also find skin care tips for the busy VP. As I have mused earlier, the diversity of content and the manner of its organization militate against rapid retrieval of information that is required by, say, a harried system administrator trying get 400 impatient users back online.

Users approach documentation like they approach the door to their dentists' offices

They don't want to be there and they want to get in and out as quickly as possible. So, not only do users want to find the information they need quickly, but when they find that information, they want to spend as short a time as possible reading before getting back to work. An informal, friendly and perhaps colloquial style might be suitable for blog entries whose purpose is to opine, entertain, amuse, infuriate, or provoke discussion. However, for the impatient user, it's probably better to sacrifice some friendliness and immediacy to avoid the risk of being misunderstood.

For instructions, a direct, second-person, active-voice style is probably the way to go. Translators and readers for whom the instructions are in a foreign language will be especially grateful for it.

The book is not (just) dead (trees)

The word “book” seems to conjure up images of a ream of printed pages glued together down one edge whose contents are intended to be read from start to finish. However, for the technical writers in Sun's software Information Products Group (IPG), the book is merely a container within which to aggregate and organize a set of related topics. Because any topic is more likely to accessed randomly (for example, through search) than in its context in the book, the content of the topic must be as short, snappy, and relevant as a blog entry.

One advantage of aggregation by a human who is familiar with the content over aggregation by software is that the order and grouping of topics can indicate sequences and choices. And the gathering together of topics in a single container enables readers to get some idea of the amount of information on a subject. For example, gathering the information in a book gives a clear overview of the sequence of operations required to enable Oracle RAC to work with SolarisTM Cluster software.

Needs of all users must be met

To be able to sell to customers such as US Federal government agencies, Sun must ensure that its information products meet the requirements of Section 508 of the Rehabilitation Act of 1973. This section “requires that Federal agencies' electronic and information technology is accessible to people with disabilities.” For this reason, if for no other, Sun could not completely abandon traditional, text-based instructions in favour of screencasts and videos.

That said, screencasts, when properly done, are a valuable supplement to more traditional, text-based instructions, especially for sighted users. Furthermore, the production of screencasts can actually benefit traditional, text-based instructions too: If a technical writer is to produce a screencast, the writer must actually perform the task that the screencast is illustrating.

The Application Server 9.1 Tell Me, Show me Page, though a rough prototype, offers a vision of what the table of contents for thoroughly modern user documentation might look like: text for users to read accompanied by moving images for users to watch.


I seem to remember also that technical manuals are unsigned because of a lawsuit in which, following a user injury not prevented by the directions, the author got sued by the injured party. So beware, all you tech authors re-converted to bloggery. I also agree that when I am looking for the solution to a problem (and let's face it, NO-ONE reads the manual except as a last resort), I want to get in, find it and get out. I don't want to have to page through screeds of chat, or worse, be forced to watch minutes on end of videos. There is no substitute for a properly indexed user manual, preferably available both on paper and online.

Posted by r v on June 22, 2007 at 11:20 AM PDT #

r v I know what you mean about never reading documentation except in desperation. I'm exactly the same myself, and I write the stuff for a living.

Posted by Paul Davies on June 22, 2007 at 11:26 AM PDT #

Paul, this is a really nice entry. Thanks for pushing forward the discussion. One more thought on the "Books vs. Blogs" comment (which I'm glad generated some controversy!).

One advantage to Blogs is the immediacy. You don't ever need to wait for the next revision of something. There is no next revision, you can just fire away as soon as you learn something new. There is obviously always going to be a place for books/manuals, but I think the NetBeans is an example of a team that does a great job using their blogs as a way to constantly bring new content to users. A few of them have used their blogs to become cornerstones of the entire community (and in fact have hugely contributed to growing that community). You might want to check out Romen's or Geertjan's blogs as examples. It's almost like the difference between a book and a newspaper, it's not that one is wrong, but they're for very different things. I just think that traditionally we've spent too much effort on manuals and can put more effort into the "newspaper" style of doing things.

Posted by Steve Wilson on June 23, 2007 at 04:08 PM PDT #

It's almost like the difference between a book and a newspaper, it's not that one is wrong, but they're for very different things.

I think this is a very important point. A newspaper is an ephemeral reporting of a point in time. A book is a long-lasting record that has been organized and whose information is easily retrievable.

Similarly, I think that blogs are a great immediate medium to get people excited about a product or a nifty product feature or to communicate news about a product. However, I don't think that ephemeral personal enthusiasm is a good substitute for a manual that is well organized, authoritative, and provides all relevant information in a known and searchable location.

Posted by Janice Gelb on June 24, 2007 at 10:21 PM PDT #

Paul, I'm another writer who is glad that you extended this discussion. It is an important topic! Both screencasts and traditional information delivery mechanisms have a role. Working out what those roles are is an exciting challenge.

Seems to me that blogs are good for more experienced users only. Not sure that more novice users are helped, as blog content (when done well) dips directly into an already understood topic. Traditional information delivery methods provide the systematic direction that novice users need. I do think both have a place, and thus I don't see that blogs can replace traditional docs.

And I'm not convinced it's useful to make screencasts of wizards. The whole point of a wizard is to allow a user to step through first before acting, if a user wants to learn what's what.

In fact, I think screencasts of any procedure are a problem, because I don't have a monitor large enough to watch the screencast AND do what it tells me to do. When I have to take notes so that I can then do the work, I'm one unhappy user.

Posted by SueAnn Spencer on June 29, 2007 at 03:56 AM PDT #

Post a Comment:
Comments are closed for this entry.



« July 2016