16 March 2018

On the impossibility of writing adequate technical documentation

A developer enters the office:

"We have sold our customer a sausage 1.0. We need you to write down the recipe by next Tuesday.

Just to help you get started:

I had a slice of the sausage for breakfast this morning. It was light brown with some darker parts. It was about this thick. [indicates between 5 and 38 mm with his fingers]

Unfortunately, I don't have a real sausage or even a picture at this point, but you are welcome to go to the kitchen. There we have a glass of jam. Use that as a reference until we come up with a proper drawing.

By the way: Our prototype sausage is made from pork, but the customer version will probably consist of horse meat. We are also discussing shifting to a fully vegetarian product. The final decision will be made in Q3.

To give you a heads-up: The sales departement just came back from the tradeshow. They have sold 5 million pieces of sausage 2.0. We need to document that asap. Development will start in March 2021.

Get moving!"