Favorite tech writing dogmas

I’m usually wary of dogmas, but some just won’t go away, they assert their eternal truth in uncanny ways. I’ve recently found some new ones, so I now have four five tech writing dogmas:

  1. A new tool will not fix broken processes.
  2. No matter how cool you are as a software company, don’t build your own help tool – it’s not worth it.
  3. Don’t invent yet another universal standard. – from xkcd’s How Standards Proliferate
  4. Following a style guide will not make you a good tech writer (unless you understand methods and processes such as topic-based authoring and single sourcing as well) – from Scriptorium’s The latest style for tech comm: adding value
  5. “No matter how much you try, you can’t stop people from sticking beans up their nose.” (This metaphor can apply to customers who use your documentation or to non-documentation managers who make decisions about documentation.) – from Jared Spool’s highly entertaining and insightful post

Your turn

What do you think: Are these some of the eternal truths in the world of tech writing? Have you encountered them? Or are dogmas inherently silly and evil? Please leave a comment.

From SME to tech writer in 7 steps

My colleague Mattias Sander writes today’s guest post about his journey from an SME to a tech writer – which is a noteworthy answer to my post two weeks ago why not to hire an SME for documentation. I thank Mattias for the permission to reprint the post from his own nascent blog The Techwriting Engineer.

I work as a professional technical writer even though I am really a subject matter expert. This provides a lot of challenges and opportunities.  Before my current job I couldn’t care less about the uses of en and emdashes, something that has now taken up at least an hour of my life. More importantly I did not have a clue of how to produce quality technical information. What I have is the problem solving skills and natural curiosity of an engineer – willing to analyse and solve any and every problem I run into. I also live by the philosophy that the best way to learn is by doing. The quickest way to learn a new skill is to find someone who already masters that skill and mimic as best you can – naturally taking into consideration that your problems might not be the same as the expert’s – and filtering accordingly.

The first thing I did when starting this job was to find a book on technical writing with good reviews – Developing Quality Technical Information – and then starting to produce my very first user manual. The result left much to ask for – but still had the focus on task orientation – with clarity and concreteness being the most important properties. Choosing this book as my techwriter’s bible was a good choice as it’s easy to use, easy to understand and it’s easy to find what you are looking for in terms of specific topics.

The challenge I now face is how to get a grip on using topic based authoring and structuring content so that it’s easy for my users to find what they are looking for – hopefully making their life a bit easier – because that’s really what user documentation is all about – helping users perform their daily tasks, isn’t it?

The title of this post seems to promise a seven step procedure, so here goes…

To produce quality user documentation – follow these steps:

  1. Buy Developing Quality Technical Information and read it from start to finish.
  2. Find out who you are writing for and put yourself in their shoes.
  3. Research what information would really help them do their jobs (or install their microwave oven).
  4. Write down the questions your users need to have answered, write down what task they need to perform and what reference information topics they need to have at hand.
  5. Produce the user documentation – using the book as your bible. Make use of the checklists in the appendix for checking the quality of your documentation.
  6. Ask SMEs and fellow techwriters to review and edit your documentation – based on different levels of edit.
  7. Kick back and enjoy the feeling of having helped Mr Smith install his new microwave oven in time to surprise his wife with a real microwave gourmet dinner.