It is not uncommon to see job advertisements looking for technical writers with software development background, especially for projects or positions that will be primarily dealing with developer documentation. And it is fair to think that this is a pretty logical and straightforward approach—you want to hire someone who knows the inner works and details of something to explain how it’s used. However, this might not be as easy as it seems at first sight.
The primary tasks for most software developers are to write efficient code and know how the software works internally. This internal perspective is actually their point of view at the software most of the time, as the interaction with the external user perspective is mostly limited to following user stories and UI mockups that are not actual user requests and feedback in their organic form. Instead, if properly created, they are presented to developers in a convenient format that should allow them to do the implementation without having to even think about the reasoning that lies behind them.
“Raised an exception” means one thing to developers and absolutely nothing to users.
The fact that one has spent a significant amount of time looking at things from one perspective, likely means that it might take some effort to make a shift. In this case, this is the shift from the perspective of an engineer who creates things, to a user who is actually supposed to use them. Apart from the ability to step into the user’s shoes, even when the user is a fellow developer, here are a couple of other skills that developers might benefit from when (willingly or unwillingly) writing software documentation:
- Good grammar. Avoiding any mistakes that would make the content look unprofessional or introduce ambiguity is probably the most important requirement for a properly written document. Even though a typical developer job usually involves some formal or less formal writing, documentation is written for the external audience and requires documents to be professional and flawless.
- Conciseness. Getting used to writing short sentences with clear and simple vocabulary.
- Audience. Knowing who you are writing the documentation for. There might be several different types of users with different levels of technical skills or knowledge about the product. Spending some time analyzing the audience is really beneficial for a technical writer coming from a software development background as it helps shift the perspective towards how different types of users see and use the product.
- Understanding and following the style guide. If there is a defined set of guidelines related to the format, grammar, tone, voice and other important aspects of created content, it is important to understand and follow them in order to keep the quality consistent and make sure that your content is in line with the company’s and product’s standards, branding, and identity.
- Research. Even though a typical developer job does involve research, finding reliable sources of information for your documentation might differ, especially when trying to explain general concepts or synthesize data coming from several different sources.
On the other hand, software developers do bring some assets to the table from the very beginning:
- Understanding the technical details. Technical writers who come from a software development background have much better understanding of all technical aspects of a functionality that needs to be documented. This is beneficial for developer-oriented documentation, but also helps when providing overviews of technical concepts behind functionalities intended for non-developer audience.
- Ease of communication with engineering teams. “Speaking their language” would probably be the best description of the benefit that a developer-turned-writer has when talking to fellow engineers, compared to a technical writer coming from a non-technical background.
- Independence in working with example code. One of the best practices in developer documentation is to provide meaningful code examples that will allow users to understand and adopt the functionalities quickly based on existing code. This is where a coding background is a true game changer as it provides independence from engineering teams in writing and testing example code.
Do developers actually want to become technical writers?
When looking at the important points and requirements for a full or partial transition from software development to a technical writing career, it seems clear that an average software developer, with adequate practice and training, should be able to perform technical writing tasks reasonably well. However, from a personal point of view I can say that this type of transition doesn’t happen that often in practice. I’ve only had one chance to work with a former software developer who became a technical writer after 25 years of software development career, and their technical writing skills were indeed impressive. In this specific case, the transition was motivated by burnout and the need to do something different after a lengthy software development career. On top of that, the person in question is a native English speaker and also writers documentation in English, which made things slightly easier.
On the other hand, some of the reasons why developers rarely choose to switch to writing documentation may be:
- Lower salary. According to Glassdoor, a Software Engineer in the US earns 117,803 US dollars annually on average, while a Technical Writer earns 77,144 US dollars.
- Language barrier. Technical writers often write documentation in foreign languages. While this might be something that’s expected from a linguist who has education and training in the specific language, this is often not the case with engineers. If they work in an international environment, their use of a foreign language usually boils down to internal communication that requires some level of accuracy and comprehensibility, but not the level required for software documentation.
- Switch of field. Even though both software engineers and technical writers work in the same industry, there is still a big difference between engineering as a technical discipline and technical writing. Even though there’s “technical” in its name, it still essentially belongs to the domain of humanities. This difference in competences and potentially aptitudes can be one of the key factors that would deter an engineer from dealing with documentation-related work.
Ultimately, there seems to be a relatively clear skill gap that engineers have to fill in order to be successful as technical writers. Even though the gap is not too big and shouldn’t be an issue for most, there’s still the question of motivation to take up a job that is not paid as much and can require getting out of a technical comfort zone into a different field. This seems as a solid set of reasons to continue seeing a relatively insignificant number of engineers who take up technical writing, especially as a complete career switch.
