Why technical writers can rescue us
What is the article about?
Technology and software are becoming increasingly important, but also increasingly complex. How do we ensure that we still understand the code we write today if the developer is not available? Where do we centralise our knowledge about the product “software”? How do we create standards in development that we can rely on? There is an answer to all these questions: cultivating technical writing.
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.
And now? Technical writing rescue squad!
Let’s start working in a strength-orientated way. We’re already doing that in so many other places! Let’s work together to ensure that the software we write today doesn’t become a legacy product in 10 years and only God knows how it was supposed to work. Let’s not waste the precious time of our developers by having them answer the same old support queries that could simply be written down and made available centrally. Let’s make sure that logics and contexts are intuitively understandable by describing them.
You can see for yourselves: Technical writers can “rescue” us in so many scenarios that arise in the everyday software development world.
So what’s the problem? Too many developers have never heard of technical writing and the profile has not yet become widely recognised in software development. Here at OTTO, we want to change that and currently have an open position.
The technical writer rescue squad will soon be on its way to you with a breath of fresh air!
👉 Read this one and more interesting articles on our Tech Blog.