Technical Writing Part 1: A Brief Introduction
As more and more services, applications, and other products get released to satisfy broader or more specific targets, the importance of the technical writer gets bigger and bigger. You may have a quality piece of software but, if the customer doesn’t know how to use it or how to find more information about specific features, then you won’t get much traction.
Isn’t everyone technically a writer?
Technically correct, the best kind of correct
Provided you had access to a decent education, you learned how to write. However, being a technical writer is much, much more than that. From having knowledge about the subject, to being able to explain complex information in a smooth and concise way, a technical writer must have a rich tool belt of skills.
At my origins, I was a copywriter for a website and specialized in the gaming industry. From news articles to reviews or guides, I had to learn a lot and write in such a way that readers were drawn in to my work.
As a technical writer, however, the paradigm shifted: users come to the documentation of a product not because they don’t have anything else to do. They come because they have a problem or want to learn something essential.
Know your role and fulfill it
Ain’t nobody got time for that
As such, you need to focus your work on satisfying the user with the required information. If you are writing an installation guide, the client doesn’t want to skim through paragraphs upon paragraphs of product history. He/she just wants to know the procedure of installing the software, plus any prerequisites or additional configuration they must perform.
To help in this role, you should strive for a few things:
Brevity: Do not use more words than you have to.
Clarity: Avoid long sentences, specific jargon, or obscure abbreviations.
Simplicity: Do not go into detail if that information isn’t deemed necessary for the user.
Structure: Use headings, ordered and unordered lists, as well as emphasis when necessary to organize your information.
Style: Maintain a coherent style from start to finish
You don’t know everything
I know that I know nothing
In an ideal world, the technical writer is a subject matter expert and knows the ins and outs of the product he/she is writing about. In the real world, you may not know everything or you may not have enough access to the product.
As such, a technical writer must know not only how to communicate with the customer through the documentation, but also how to communicate with the rest of the team through conversations. Whether it’s asking a developer about a specific feature or going to a quality assurance analyst to learn more about a workflow, you need to maintain a pleasant atmosphere so that the information flows from them to you and from you to the end-user.
Refine, refine, refine
I live, I die, I live again
Last but not least, being a technical writer is a marathon, not a sprint. Your work will go through lots of drafts, reviews, and refinement before it reaches the end user. You are sometimes at the mercy of product management and you may see large chunks of your guides be removed alongside the actual feature in the product.
Learn to handle the feedback, even if may sometimes be worded in a harsh manner, and strive for improvement. Your last document should be the best you’ve ever done.
Practice makes perfect
Just do it
Technical writing may sound complex, especially after everything I’ve mentioned above, but don’t let it get you down. With enough experience and great people to learn from, you can get the hang of it. Just remember to always improve and apply some critical thinking in everything you do.
Stay tuned for more articles about technical writing throughout this series.