On Becoming a Technical Writer

One of my many role models once said, the reason as to which she started out into technical writing was as a way for her to pen down her new learning and findings in her evolving journey as a software developer, to help in her times of “getting lost when re-facing the same issue/bug”.

An in-depth means of teaching, explaining or breaking down a logic asides other means is through writing as it allows you explore all of your creative thinking at your own convenience without having to worry about stage fright.

Technical writing encompasses all of these and more, it involves the documentation of complex technical process or ideology into simpler understandable formats. It started out with User or instruction manuals for technical products or services and has since advanced to writing about technical or specialized topics, such as computer applications and tools, software development languages and frameworks, medical procedures, environmental regulations etc

The Skills:

Technical writing skills come naturally to some and to others it’s learnt, but in all, some of the vital skills needed to be a good technical writer involves:

1. Strong writing and communication skills : The ability to relay complex meanings and terms in simpler and comprehensible words to your audience are a-must-have, as they drive down the essence of coming on to read your article i.e getting to understand what they hadn’t all along.
2. Technical experience / skill relevant to the field : Conveying a message implies understanding and mastery of it, knowledge and experience in the field of what you write about is a requirement. It’s presumed you currently work or are knowledged in the stated field and as such know your onions, many technical writers hold technical positions in their fields such as Software developer/engineers, Infosecurity analysts, etc. Writing in a field you are well conversant with goes a long way in churning out a great article.
3. Interest : Having (huge) interest in technology gives you an edge while venturing into technical writing as it spurs and keeps you up on your feet in scout of new technologies to learn and write about.
4. Research skill : Writing involves (a lot of) collecting and comparing data and findings from different sources combined with your personal knowledge on the topic to turn into valuable written information.

The Process :

Writing a technical article can be a lot more different from a usual essay and could take quite a while as most times involves having to recreate simple to complex practical technical steps in order to relay your aim . As a result of these, before and while writing, the following precise steps are always taken so as not to create drastic flaws in your article:

1. Know your audience : The reader is always at the forefront of a technical writer’s mind, Knowing the category of readers you’re writing for goes a long way to simplifying the rest of the task. Writing an article meant for beginners in bogus terms while using unfamiliar technical or advanced parlance won’t do the trick in passing down the message. Your audience defines the texts used and how your information is conveyed. To help know your audience more, the following questions should be considered before starting up an article:

• Who are they?
• What do they need (to learn from your article) ?
• Where would they be reading your article?
• Why would they be reading?
• How would they be reading?

These questions go a long way in helping understand your audience.

1. Map out your article : Writing a technical article can seem like a complex uphill task and a bit confusing as to where to start from but with your audience clearly defined, creating a map or guideline (start <—> finish) comes off a lot easier. Outline the necessary information your audience ought to gain from reading and possibly turn them into points / guidelines, some writers like to outline all of these i.e create an overview at the beginning of their article to give the reader an understanding of what to expect as they move on. Having a powerful introduction in your article also helps you know the next path to take in your article. Creating a map or guideline helps to highlight other areas you might not have thought about or even know and would help to get you more acquainted and prepared.

2. Feedback Iteration : No writer is a mountain of knowledge, just as reviews and feedback are encouraged amongst career professionals in technology, so is it in technical writing. Getting technical review and feedback on your article from colleagues, professionals, field experts etc alongside reading your own article with the mindset of your audience helps to spot both grammatical and technical errors that might have escaped your scrutiny before publishing your article.

3. Content Creativity : Now that you understand your reader and have a map or guide to your article, infusing creativity by maintaining a style of writing while clearly communicating your message in the body of your article goes a long way to keeping your reader’s attention to the very end. Here are a few examples:

• Choice of word(s): Choosing your words and including more details where necessary helps your article be more comprehensible.

Example : Open the command line and perform XYZ actions inside the “documents” directory

Improved : Open up your command line, go into the “documents” directory by typing “cd documents” and performing XYZ actions.

• Constant use of Active voice : Use of Active voices in texts are a lot easier to read and understand than passive voice.

Example : Over 350,000 packages are contained in the Node.js npm package registry

Improved : The Node.js npm package registry contains over 350,000 packages.

• Sentence structure : Placing the important information in the first sentence goes a long way.

Example : It is always advisable to back up data before carrying out a database update. If you do not adhere to this, there’s a huge possibility of permanent data loss

Improved : It’s advisable to back up your data before carrying out a database update to avoid permanent data loss.

• Avoid technical slangs/abbreviations/jargons : It’s quite easy getting caught up in writing an article and churning out all that information, that we unintentionally make use of abbreviation/slangs/jargons familiar to ourselves and league of friends or colleagues. When writing articles and intend to use unfamiliar terms, it’s best to state them out in full, define them and thereafter refer to it with the abbreviations rather than jump straight ahead while leaving your audience in the dark.

Example : The MVC pattern is widely accepted across various frameworks.

Improved : The Model-View-Controller (MVC) pattern is widely accepted across various frameworks.

• Initiate a Task Based approach : Most technical articles are in form of tutorials or D.I.Y’s for the reader, so writing your articles in form of steps can also be a great way to make it more comprehensive. Ensure to follow the right order of steps to give your writing a natural flow.

The Benefits :

There are lots of benefits that come with being a technical writer, some of them include:

1. Constant learning as you continually try to keep up with new technologies, improve on your reading and writing skills, dive into new areas and getting constant feedback. It’s an upward growth scale.
2. It’s a prized and profitable skill , as anyone who’s really good at conveying technical complexities in simpler terms to users are termed “valuable” to organizations who are always willing to pay heavily to have them . Some popular sites to apply for a paid technical writing gig are Pusher , Scotch.io , logrocket etc
3. It’s a career boost and additional skill-set for individuals in technology, as they are seen as being able to quickly grasp, breakdown and relay the technology use and importance to the user.

Get started with technical articles, sign up to be a guest writer on the Findworka publication, Register here: