Why technical writers can rescue us

The problem

I bet that every developer has been at this point in his or her career: when you've been programming for so long that your eyes are starting to tear up a little, you've produced what feels like a million syntax errors and have grudgingly fixed them again, and generating a different error message is already considered a daily success. Until the moment finally comes when everything suddenly works. And why? Well, only God knows!

What a really funny meme from Reddit so humorously depicts becomes a problem at the latest when 3 weeks later your colleague wants to know how she can get your code to work. Unfortunately, she reacts slightly irritated to your suggestion to simply drop by at church next Sunday. 

That this is not an individual case becomes clear when you consider that the image above has received more than 17,000 upvotes. At this point, something should be obvious: if we want to avoid wasting 254 hours trying to understand our software, we need to change the way we work!

A solution

There is certainly no universal remedy, but there is a promising approach: technical writing.

Never heard of it? Don't worry! Technical writers at OTTO help us to take the developer experience to a new level. At OTTO, this new role is currently being developed with two different technical writer profiles:

The team technical writer

As part of a software development team, this team member supports the documentation of software to make developers' work easier. For example, technical writers save the naming of variables (so you don't have to spend another 20 minutes wondering what you meant by "values 2_tmp"). They also create standards that are comprehensible and helpful for developers. They write READMEs that actually live up to their name: they are not empty or contain just one sentence. They standardise documentation and centralise information so that knowledge about code functionalities is not forgotten as soon as an employee no longer works on it. 

To support the team effectively and provide context for the documentation tasks, this team member is firmly integrated into the team. The role is present at all relevant meetings such as the daily, planning, estimation and discovery meetings.

The cross-domain technical writer

As the name suggests, this technical writer works independently of the team and domain context. At an organisational level, this role provides support, e.g. with documentation for cross-domain contexts such as API or design guidelines or accompanies knowledge centralisation measures.

The role shows teams that do not yet have technical writing support the added value of the role with sparrings or discusses and communicates the relevance of technical writing in a large company like OTTO to management.

The mission

At OTTO, almost 2000 people work on software every day. If our goal is to create the best possible end product, we can only achieve this if we work together. If we make it clear what we are working on and how we are working on it. If we don't try to reinvent the wheel on which an entire car is already travelling at the other end of the OTTO Campus. 

Developers are busy enough getting their code to work. They have chosen to make a living with languages like Java or C++ instead of documentation in German or English for a reason. What I want to say is that developers are clearly focused on programming and very few of them enjoy documenting their codes.

But technical writers enjoy it even more! And their job is to create technical documentation and to communicate complex relationships in a simple way.