Training that technical writing muscle

Sebastian Greger

Many think of designers as those restlessly creative, artist minds whose work consists mainly of producing ever new ideas and concepts. While that kind of work is genuinely fun to do, I have always seen design mostly as the work of digging ever deeper, working out the details, and most importantly taking the perspective of somebody unfamiliar with the subject.

Dreaded by many, I therefore enjoy some technical writing from time to time. I did that full-time at one stage in my career, but today mostly as an integral part of involvement in bigger projects where writing documentation or instructions help to thoroughly reflect on and verify design decisions. I’d even go as far as to say that writing documentation is one of the most cost-effective means of quality assurance.

That muscle needs to be trained from time to time, and so I took on the task to document a rather small, but abstract task with the Kirby CMS and work out the details: designing the storyline from the basics to the final code sample, figuring out how to create code snippets that are verbose enough to understand but concise enough to not overwhelm, all the way to meeting the tone of other texts in the Kirby Cookbook – this has been a fun little exercise.

If you want to see for yourself, here’s the Kirby Cookbook recipe “Batch update content”.