DocTrain West 2009: Richard Hamilton on “Managing the Move to Structured Content”

Richard Hamilton ran a session to talk about managing the move to structured content. Richard is a really pragmatic guy, so he talked about the why, what and how of managing the transition.

He started with several reasons of why and when not to transition:

  • When there’s neither a benefit for the bottom line nor for the customers/users
  • When it leaves you without a productive and operable documentation environment at any stage
  • When you cannot commit to the new process (i.e., you’re afraid to burn your bridges behind you)
  • When you cannot train or run a pilot project

To select what to carry over, he advocated converting only the used, required contents – and when in doubt to leave it out. He also said to carry over all the existing semantics, but not to add any new semantics, unless they add a proven value at reasonable cost: Don’t let the perfectionists run wild and build a more perfect solution – it’s difficult enough as it is.

For the “how”, he suggested to get outside help, esp. with the actual conversion – though that may require to clean up legacy content to get it ready for sensible conversion.


DocTrain West 2009: Ann Rockley’s keynote “Moving to Structured Content”

Ann Rockley gave her keynote address about how to move to structured content.

She focused on the project stages in implementing structured content. To get wary or hesitant writers on board, it’s essential to teach them, so they understand how the way they work will change: First, teach the concepts as well as the benefits which are consistency, reusability, guidance in writing and enhanced productivity when you don’t have to worry about stuff like structure and formatting. Then teach the modeling of content, then the guidelines for writers to adhere to. (The address did not discuss the business case and change management – for time reasons, I guess.)

She emphasized that structured writing should be taught separately from the tool, lest writers will focus on the tool rather than concepts and process. Then get a tool which matches the writers’ skills.

Mitigate the “fear of the thud”

We tech writers may look at comprehensive, well-done documentation with pride. Alas, our readers may just judge the book by its cover and fear the thud when inches of documentation hit their desk.

Tom Johnson wonders “How Much Should You Document? Everything?“, and the comments discuss the virtues of doing it all versus doing it well.