Mark Baker

Designing for Feedback

We were discussing the biggest challenges in Tech Comm at the last STC Toronto brunch and we all seemed to agree that the difficulty getting feedback on the effectiveness of the content we create is the biggest challenge. The things that really matter in technical communication is whether users can achieve their goals after finding and reading the docs, and whether that makes a difference in whether they buy from you again or speak well of you to their friends and colleagues. These things are incredibly difficult to measure. You are just not there to see them happen, and it is very difficult to separate their effects from the effects of the work that designers, developers, sales people, trainers, field engineers, and support staff do. read more

The Death of Hierarchy

Hierarchy as a form of content organization is dying. A major milestone — I want to say tombstone — in its demise is the shutdown of the Yahoo directory, which will occur at the end of the year according to an article in Ars Technica, Yahoo killing off Yahoo after 20 years of hierarchical organization. (Actually it seems to be offline already.)

As the article observes, a hierarchical directory made some sense when Yahoo was created:

In the early days of the Web, these categorized, human-curated Web listings were all the rage. Search engines existed, but rapidly became notorious for their poor result quality. On a Web that was substantially smaller than the one we enjoy today, directories were a useful alternative way of finding sites of interest. read more

Designing topic types

A number of readers have asked me to write about how to design a topic type. Although it can sound complicated, especially if your bring XML schema definitions into the mix, designing a topic type is actually pretty simple.

Before we begin, though, set aside all the issues around XML. XML has nothing to do with topic type design. It may have a lot to do with how you implement your topic types (or nothing to do with it), but it has nothing to do with how you design them.

Needed information in a specific form

A topic type is essentially two things: read more

Don’t Lean on Development’s Agile Process

Don’t just try to fit into development’s agile process. Create your own lean content development process.

Technical writers are increasingly finding themselves involved in the agile process of the development organization. The most common way this happens is that a writer gets assigned to the team for a sprint and is expected to produce documentation in the same sprint as the developers produce the feature.

This has one huge plus for writers: development cannot declare the sprint complete until the documentation is done. This means that it is in the interest of every developer to help ensure that the tech writer has what they need to get their work done. Given that getting information when needed is a major issue for many tech writers, this can be a very big win. read more