Archived Seminar Review: Process Re-engineering for Topic Based Authoring

Introduction:

The STC website has about 90 archived seminars, webinars, and presentations. Access to all this material is included in your dues. They are mostly over an hour, and cover a range of topics. As a public service to STC members, I decided to watch and review them all. One at a time.

Review Number 1: Process Re-engineering for Topic Based Authoring.

This presentation focused on the difference between how an organization produces topics and how an organization produces books. The speaker, Rob Hanna, is engaging. His slides help you follow along with what he is saying, and probably help him remember what he is saying. It is a bit boring to look at slides and hear someone talk, without seeing their body language, but that's what you get learning on the internets in 2012.

Did the speaker make it clear what the problem that he was trying to address is?

Yes. Writing involves process. Writing differently may require a change in process. In many cases, documentation is written by a group of people, so the problem of changing process is bigger than it would be if it were just one or three writers.

Did he identify a real problem?

The question here, is really, is writing topics that much different from writing books. Rob Hanna makes a strong case that the writing is different.

Did he explain what the parts of the problem as he sees it?

Rob made the case based on his own experience that writing topics as a unit of output is a different beast than writing books. Here are the differences as he sees them.

Topics:

- often have many authors contributing to a book.

- each may serve multiple audiences and even products

- are created iteratively,

- are often presented based on external shaping measures, like templates.

- are well suited for modular hardware and software products with short development lifecycles or long lifespans.

Books, on the other hand:

- often have one author each.

- usually serve a single audience and products

- are developed linearly.

- include and even require manual formatting.

- are well suited for highly technical or one of a kind products with a long development lifecycles or short lifespans.

His definition of a topic based architecture seems standard, but I disagree with one part of it. He suggests that writing topic based content requires standard information types, descriptive titles, and content that needs only navigational reference points for context, and can be read in any order.

I think that standard information types can help produce clarity by making writers focus on saying one thing at a time, and saying it to completion. And I agree that descriptive titles are important for helping users find what they are looking for quickly. I do not agree that topics, even ones that are completely written and make sense on their own, work as well on their own as they do when they've been ordered by someone who knew them all.

Rob did a good job of making it clear that topics are not suitable for every application. In my experience, topics can be sold as a panacea. Rob makes it clear that moving to a topic based content development methodology is not the way to go for all organizations, everywhere.

A peripheral misconception about topics that this presentation clears up is that of single-sourcing and topic based authoring. A big part of writing good topics is writing for re-usability. Writing for re-usability is different from writing for reuse. A well written topic is not one that is reused a lot, but one that can be reused. 

Rob Hanna goes on to say that single-sourcing practices can be applied to both topic and narrative based writing methodologies. However, he believes that topics allow for a more flexible re-use, while re-use of narrative content must be more planned and predictable.

After explaining how topics and narrative writing methodologies differ, Rob explained how the writing processes for topics and books differ.

He identified the sheer number of topics that get produced as a primary process difference. The content that made up 10 books might be thousands of topics, and thousands of things are clearly harder to deal with than 10. This difference touches file naming conventions, content storage considerations, versioning, and release management at least.

Storing thousands of files based on filenames, no matter how descriptive, becomes less and less workable the more files you have. When writers are used to owning whole books, it can be hard for them to relate to a much smaller unit of work. The modularity of topics means that different versions of a topic might be released for different products at different times. The iterative nature of writing topics means rethinking the roles and stages involved in content production.

Did he have useful suggestions on how to solve the problem?

Rob suggested that, if your organization has decided to start producing topics, you should build the best system you can using the tools you already have in place. There are a number of enterprise component content management solutions available, but he doesn't think most people will know which one is right for them until they've discovered their needs using what they already have.

He suggests that using spreadsheets to track content, source code versioning tools to handle versions, and webservers to handle access draft publishing are cheap ways of getting started.

As for roles, Rob thinks these are pretty standard for topic based authoring:

- writers to write topics.

- editors to edit topics when they are written.

- librarian to manage and track topics and versions, and dispose of them as they expire.

- architect to build content maps that combine topics into useful information products.

His proposed workflow for topic production goes like this:

1)Map existing content to identify gaps

2)drafting topics

3)editorial review while other topics are being written

4)technical review while other topics are being written and edited

5)approval of topics as they come in

6) and publishing of all the topics in an information production.

This cycle should be shorter than producing books, with less downtime for each role as the topics move through more quickly than books would, being smaller units.

When it comes to gathering information, he recognizes that subject matter experts may balk at reviewing such small units of content, especially if they are used to reading a section of a book. To deal with this, Rob suggests providing reference materials alongside the topics under review. That way the SME can provide technical feedback in light of the topics likely usage or the gap it is meant to fill.

Rob reiterates that this type of process reorientation is time consuming and expensive. He says that it can take up to two years of tweaking and practicing until topic based content production is fully implemented.

Was the talk interesting?

Yes, the seminar was interesting because it is cool to find out from very experienced people how other organizations work. It was also interesting to note that something like half the audience was producing topics as their job.

Was the talk helpful? For who? Why?

This talk is useful for people who are aware of both the topic based and narrative based approaches to documentation. It can provide some reaffirmation to those who are already writing topics, and like doing it, and to those who write books, and like doing it. The seminar is most useful for organizations who are moving to topics, or who are thinking about moving. The seminar is less useful for those who don't know about topics. Their needs would be better suited by in an introduction to topics rather than the processes involved in writing them.