5 steps from legacy documentation to topics

To move to topic-based authoring, you need to convert existing documentation into topics. The efforts shouldn’t be underestimated, but it’s actually a pretty straightforward process. I’m describing how to convert sections in manuals, but it’s much the same for most content, whether it’s FAQs, wiki articles, training materials, etc. Prerequisites Some knowledge of topic-based authoring. [...]

Writing to create context to think – and work

The skill of technical communication is to create a context in which other people can work. – This concise insight helps me to stay focused on my users and their tasks, even if it’s not totally original. I came to it via an article by Tim O’Reilly in his Financial Times article “Birth of the [...]

Are serifs or non-serifs easier to read?

Are serif fonts easier to read than non-serif ones? No, is the conclusion in Alex Poole’s exhaustive post. After reviewing more than 50 studies, Alex comes to the conclusion that “serifs or the lack of them have an effect on legibility, but it is very likely that they are so peripheral to the reading process [...]

When topics don’t quite work

If a topic in your documentation gives you trouble, seems homeless or doesn’t quite “work”, it’s probably because it is mixing topic types. The company I work for has started to roll out topic-based authoring over a year ago. We’ve seen several benefits already: Topics are easier to find and follow for users and more [...]

Recommended read: Practice technical writing

Becoming a better tech writer requires practice. Mike Pope, tech editor at Microsoft in Seattle, has a brilliant blog post about 12 ways to practice tech writing. The catch is he means “practice” like a musician, so you learn to do stuff better than yesterday – instead of just doing the same things over and [...]

How a degree helps a technical writer

A college degree can help you in technical writing, though maybe not in the ways you expect. How relevant is a college education for the field of technical communication? A couple of very good and influential tech writing blogs have recently discussed this issue: Why Tech Comm Is a Career Path of Last Resort for [...]

What’s in a (serial) comma?

An example of a missing serial comma got tweeted my way which was too good to be true: Among those interviewed were his two ex-wives, Kris Kristofferson and Robert Duvall. And here’s the guy who was married to both, Kris and Robert…

How and why to estimate writing efforts

Estimating your writing efforts and deadlines is difficult, but essential. Can you reliably estimate the time you need to write documentation? And the date when you can deliver? It often seems a daunting task because it depends on many external factors: The quality of specifications and designs. The availability of the finished product. The accessibility [...]

Index this!

An index is an important navigation device in documentation, especially in print. It helps users to quickly find key terms, concepts, functions, and instructions. In this post, I share my best advice about building an index. And I ask for your help and opinion on a couple of details. To make your index entries helpful, [...]

Master change – with skills or attitude?

In the face of fundamental changes, skills seem to follow attitude. That’s my second conclusion from Sarah O’Keefe’s webinar about “Managing in an XML environment”. Read on for my summary of her argument and my comments. (Or see my previous post “Top strategies to embrace cost metrics” for more insights.) Technical writers need a different [...]