Skip to main content

A long suffering technical writer.
Former copywriter.
Occasional journalist.
Part-time poet.

The wulfman

The ordinary documentation lifecycle

Writing documentation is a highly organised process that inevitably follows these steps:

  1. Project assignment
  2. Information gathering, i.e. running after developers
  3. "The age of constant changes"™
  4. Review of first draft
  5. Complete rewrite based on new information
  6. Repeat steps 2 thru 5 as applicable
  7. Review of final draft
  8. Approval of documentation
  9. Publishing and distribution to customers
  10. Withdrawal and documentation of hitherto unknown features
  11. Release of follow-on product
  12. Obsolescence

The wulfman

The big placebo

1 min read

It is a beloved tradition that, once a year, employees are asked their opinion. This "yearly environmental survey" is a time to assign points (or, depending on HR's preferences, characters) to everything from the quality of the hardware to the strategic direction in which the company is headed.

Fortunately, these surveys are anonymous so that employees can answer truthfully without fear of repercussions.

Unfortunately, the survey is anonymous so that the results only show that 27% of the employees are unhappy with the R&D process, but it does not provide any insight into the who and why.

It is therefore best to repeat the survey the following year in order to get some clarity.

The wulfman

Naming conventions

1 min read

Some product names are quite clever, e.g. "iPhone". Others less so, e.g. "Aygo" (I see what you did there, Toyota!).

Not taking personal preferences into account, it's probably a very good idea to leave product naming to professionals, such as augurs, shamans, voodoo priests, or monkeys with typewriters.

Under __no circumstances__ must the naming process be left to the R&D department! Before you know it, you will have to deal with "Backup Interpreter Control Module Connector 0.0.3.12 (alpha)" and "Loose anchor bolt retriever and transmitter - for US market only™".

If the milk is already spilt and you are being presented with a bunch of insane product names, don't waste your time crying over it. Simply start using acronyms: The "Loose anchor bolt retriever and transmitter" thus becomes a "LAB RAT", which is easier to handle anyway.

That'll teach them!

The wulfman

Llama expert trumps Peruvian goat herder

2 min read

It's time for the final review, when suddenly some smart guy/gal has a brilliant idea: Let's involve a friend of mine who happens to be an expert in [insert specialist field here] and ask for his opinion!

Naturally, everyone thinks this is a brilliant idea. And honestly, what could possibly go wrong...

Once Pandora's box has been opened, you will find yourself having to reevaluate topics that have been shelved weeks ago. Not to mention that you will finally get the chance to tackle essential improvements, such as changing the font face, adjusting the pagination and reducing the use of the letter "m". (I once had a proposal shot down because the secretary knew someone who was a "Scandinavia expert and (!) professor"...)

Ï don't mean to knock other people's friends. We can safely assume that some of them do have a certain amount of knowledge, and they may even be proven experts in their field. BUT: This does not qualify them to jump into any work in progress on a minute's notice and overrule results that are based on detailed knowledge of a specific situation.

Unfortunately, there is no universal way to counter the ubiquitous external expert. The best way seems to be to build up your own network of advisors who can counter any specialists that might be used in an argument, e.g. "My llama expert trumps your Peruvian goat herder".

Good luck!

The wulfman

How not to write a mission statement

2 min read

I'm not quite sure why companies write mission statements, but I assume it is in order to commit their employees to some sort of common goal. Logic dictates that the statement should be concise and easy to understand, so that the average employee can grasp what the company's goal actually is, e.g.

[Company] aims to make the world's best pancakes!

Should you ever be asked what your job is or why someone should choose your company before another, there's your answer.

Unfortunately, because of their strategic nature, mission statements are often considered top priority and as such, they are developed and written by upper management. This leads to statements such as

[Company] continuously keeps the company product portfolio modernized and updated in order to be our customers' first choice, and R&D is the main contributor to our overall vision of becoming the Leading technology supplier in [market segment], with special focus on [buzzword 1] and [buzzword 2]".

That's quite a mouthful. You can almost smell the cold sweat as the committee tries to cover all the bases just in case some C-level manager should decide to have a look and check if the lower echelons have internalized what the company really stands for.

The wulfman

So little broth. So very many cooks.

1 min read

Many companies pride themselves in having flat hierarchies.

What this usually means, is:

  1. People don't know what they are talking about, because hierarchies are by design pyramidal.
  2. There are lots and lots of tiny kings and queens who eagerly meddle with other people's territories.


When it comes to documentation there are three schools of thought:

  1. We need documentation
  2. Documentation is totally unnecessary
  3. We don't give a *#%!, just leave us alone


The fun begins when a member of group 2 decides that a certain product does not require any documentation, because:

  • it is totally self-explanatory
  • it will soon be updated anyway
  • it is virtually identical to a completely different product


When, inevitability, a customer demands documentation for an undocumented product, a new school of thought instantaneously emerges:

  • We need documentation, but leave us alone because documentation is totally unnecessary *#%! anyway