My Journey From Developer to Technical Writer
I started my career as consultant-slash-software-developer eleven years ago. Creating documentation has always been a part of my job, which included creating both internal documentation and end-user manuals. However, unlike other peers, I never felt that these tasks were a chore or that they were distracting me from my precious coding time. This should have been an obvious sign that further down the line, documentation would play a larger role in my life.
Two years ago a friend I’d met in college contacted me and asked me if I’d be up for a challenge. He also has a computer science background, and he’s been a technical writer for many years. At the time, he was growing his team; he was looking for a technical writer, preferentially with experience in software development. He knew that I enjoy writing technical documentation. The invite seemed like a great opportunity to explore my “writing-side,” and it seemed to be quite the technical challenge. The product was a low-code leader, a very complex and large product.
So I took a leap-of-faith and started a technical writing career at OutSystems. As I learned more about my role and tasks, I realized that I already did many them in my previous job — tasks like explaining technical things to non-technical people. I’d have to make sense of complex new product areas or exciting new features, figuring out what information is essential for our end-users.
Now two years have gone by, and I can say that I’m very happy I took this path! It is, in fact, a challenging position, possibly also due to the fact that the product itself is also very challenging. My main tasks are organizing information and explaining complex concepts, but also developing internal tools to increase our productivity as a team.
From a Developer’s Perspective
The software building process isn’t new to me, so I understand many of the challenges that developers face. Since I was once a developer, I can look through heaps of source code files and have a fair understanding of what’s going on. It’s an advantage because I can gather information independently.
However, though it facilitates communicating with developers, I do not really need to understand all the technical details to write good documentation; I just have to make sure that I can digest that information and pass it on to the intended audience. Being naturally curious about software and technology and having an engineering background and mindset, with a natural interest in documentation, helped me to be a better technical writer.
As someone who was previously a developer I came to appreciate some things that come with being a technical writer:
- You usually have better deadlines (documentation usually only needs to be available on the release date, which occurs some time after the code freeze date).
- You don’t have to face as many cryptic bugs.
- You get to know your end-users and get first-hand feedback from them.
- You get to collaborate with lots of different areas — not only Engineering and Support but also Design, UX, and Product Management to name a few. Be warned: interacting with more people usually means more meetings!
On the downside, especially when you start working at a company as a technical writer, you may have to sweat a bit until you start being considered an expert, both by developers and by management. Your role may be seen as closer to Support (we’re user advocates, after all) than to the product development area itself. Also, you will not get many compliments from end-users for writing great documentation, but people will be quite vocal when the documentation is missing or inaccurate.
We Don’t Need No Documentation… Or Do We?
Great products with amazing UX will need less documentation. Yet, regardless of how amazing the UX is, when there’s an increase in the product’s complexity, there’s going to be an increase in the documentation. Your standard shopping list mobile app might seem pretty obvious, requiring no documentation. But, enterprise apps or open-ended software like OutSystems — used for creating pieces of software — definitely need documentation that’s customized for different audiences of varying levels of expertise and different personas like administrators or developers.
Open-ended products like OutSystems add another hurdle to the technical writer path: we need to learn about things from R&D developers and explain them… to OutSystems developers! Wearing the tech-savvy hat to understand the product in depth while at the same time being able to stand in the user’s shoes, deciding what information is necessary from the user’s standpoint, is quite a challenge.
Technical Writing for Software Documentation
It’s hard to hire for this role — even more so at OutSystems. Finding experienced technical writers with the right tech skills, together with good English writing skills, and a good ability to explain hard things in a simple way is quite a challenge.
If you’re interested in making the transition from Developer to Technical Writer, make sure you do it for the right reasons, because you enjoy writing technical documentation, and not because you feel you’ll never become a rockstar developer. It’s a challenging area on its own, but it is a rewarding career for a software engineer that has a knack for explaining things to people.
It just so happens that we’re hiring a technical writer to join Pedro Sousa’s team, have a look at the job description here https://jobapply.page.link/sfRa
