Screencasts and Books: There's a Place for Both
By pauldavies on Jun 22, 2007
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.
blogs.sun.com - I never knew there was so much on it
To borrow the catch phrase from an ancient TV commercial for the TV Times: blogs.sun.com - 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.