Technical Writing: Practical & Theoretical Advice
If you’re looking for ways to get a tech writing job or would like to improve your existing technical writing skills, then this article might be of great help. Herein, you’ll learn the definition of tech writing, different types of tech copy, tips on how to write effectively, how to ace tech writing, where and what exactly you should study, and how to break into the industry.
What is technical writing?
Technical writing (tech writing) is writing technical documentation or any other form of communication that’s used in technical and occupational fields, such as computer software and hardware, web development, engineering, chemistry, physics, aeronautics, robotics, consumer electronics, medicine, biology, finance, biotechnology, and even forestry.
Technical communication, as defined by the Society for Technical Communication (STC), is any form of communication that exhibits the following characteristics: communicating about technical or specialized topics, communicating by using technology, and providing instructions on how to achieve something.
The main goal of technical writing is to convey information in a concise and comprehensible fashion to the end-user or reader. The problem is that the information to convey is often too complex to dissect and re-express in the clearest and effective manner, making the technical writer’s job revolve around understanding and analyzing information first before explaining it to others.
Therefore, a technical writer must possess good technical, verbal, and writing skills: verbal — for communicating with team members to find out how something works or supposed to work, writing — for conveying the learned and acquired information through text, technical — for understanding the subject in-depth, employing computer programs to create and edit illustrations, diagramming, designing, and formatting documents.
Technical writers are expected to be proficient in hypertext, word processors, graphics editing programs, and page layout software to make their technical documents.
Different types of tech writing
Technical writing covers a wide range of genres and technologies; for example, user manuals, press releases, memos, reports, datasheets, product descriptions and specifications, white papers, resumes, and job applications — are all considered to be examples of technical writing. Further below, let’s outline and characterize some of the types of tech writing.
- Technical reports are project and business status reports, legal case reviews, personnel activity reports, or expanded description of the technology, its evolution, structural, and operational revisions.
- End-user instructions are, perhaps, the most well-known type of tech writing. These are instructions on how to use any particular product or software presented in a user-friendly language. This category also includes such examples of technical writing as troubleshooting guidelines, assembly instructions, warranty descriptions, legal disclaimers, and so on.
- Feasibility studies (and corporate reports) demand precise research and adequate representation of the company’s financial results to be easily understood by different levels of employees, executives, stakeholders. Corporate reports are riddled with stats and graphs, charts for comparative purposes in the area of finance, economics, social and business practicability.
- Research results are scientific, medical papers, and other learning resources for medical practitioners and scientists to understand the procedures involved in the study and its results. Exemplary attention is given to minute details in the writing of those results as they oftentimes contain critical information, such as drug interactions or side effects.
- Policies and procedures (employee handbooks) describe the rules and regulations common for a particular organization and present instructions for employees in clear and non-discriminatory terms.
- White papers present information on solving a particular problem designed by an organization for an external audience. White papers explore problems and present authoritative solutions that readers are encouraged to adopt.
- Business plans require highly technical and operational research in forecasting, assuming, predicting, and describing business expenditures, possible losses, profit margins, competitive analysis, marketing strategies, detailed background information on the financial stability of the business and its owners.
- Case studies describe and provide an analysis of real-life scenarios and situations on individuals, groups, organizations, decisions, practices, events that reflect the subject of the study across a defined timeframe. Case studies aim to identify patterns in the data and come up with trends or generalizations to help the business or project in the future.
- Literature reviews are examples of technical writing that summarize information or provides an overview of what’s known on the subject, including the details on previously conducted research and findings on the topic, research milestones, and available results.
- Proposals are usually written as call-to-actions for an individual or a group to perform some action, hence — the writing is expected to be persuasive and convincing.
- Software specifications — a clear-cut definition of what the product/software does and how it behaves in a specific environment. Read more about software spec here.
Tips for effective tech writing
Technical writing, as has been already mentioned throughout the article, must be concise, very focused, unambiguous, and easy to understand. A technical writer needs to try and avoid, wherever possible, the use of technical jargon, overcomplicated phrases, and weak stylistic choices such as passive voice and nominalizations. Let’s define nominalization for those of you who are not yet familiar with the term: nominalization is the use of a word which is not a noun as a noun in the head of a noun phrase with or without morphological transformation (example, “nominalization” is derived from “nominalize” or “carelessness” — from “careless”). The problem with the passive voice and nominalizations is that oftentimes they are not clear and create ambiguity in the writing. Imagine, a technical writer describing the use of ultrasound in radiology or instructions on how to perform ultrasound scanning — anything that’s equivocal or not easily discernable can lead to horrendous misinterpretations or fatal mistakes — therefore, every sentence in technical writing must be as clear as it could get.
Hence — the first step that every tech writer should undertake is to examine the audience of the intended text and find out what the audience already knows about the product, service, procedure, or any other material to be covered in a document. For example, research results for a group of scientists will differ significantly from the same material presented for the general public. Tech writers don’t have to be subject-matter-experts (SME), however, they do have to communicate with SME in order to fully understand the service or product or anything else they are describing and represent their findings in the clearest and unambiguous fashion.
Let’s outline a few major principles of a good tech writing copy:
Use an active voice in your writing. The active voice emphasizes the author’s responsibility. It also improves readability and reduces ambiguity. It doesn’t, though, necessarily mean, that you have to avoid using passive voice altogether: passive voice can be used when the recipient of the action is more important than who performed it (oftentimes used in a method section of a research paper).
It’s perfectly okay to use personal pronouns for the lack of a better option. However, still, try to use that sparingly, and remember that the use of a personal pronoun is better than using a passive verb.
Use strong verbs and avoid turning verbs into nouns. For example, “During DNA damage, recognition of protein 1 by protein 2 results in the recruitment of protein 3 and repression of cell proliferation genes.” “Recognition,” “recruitment,” and “repression” are all verbs that have been turned into nouns and should be turned back into verbs: “During DNA damage, protein 1 recruits protein 2 and protein 3, which together repress cell proliferation genes.”
Keep the subject and the main verb closer together at the beginning of the sentence.
A few other grammar tips: “data” is always plural, “affect” doesn’t equal “effect,” “compared to” doesn’t equal “compare with” (where “compared to” is used when you point out similarities between different things [used primarily in literature], “compared with” means pointing out differences between similar things [used in science]), “that” is different from “which” (“that” is for a restrictive clause, and “which” is for a nonrestrictive clause), pay close attention to punctuation and do not disregard its power.
Write sentences in parallel structure. For example, “We aimed to increase the resolution and to improve picture quality,” where an infinitive phrase “to increase” parallels with another infinitive phrase “to improve.”
Each paragraph contains one main idea. Write shorter paragraphs of no more than five sentences each focused on one single idea. Give away the punchline or conclusion right at the beginning of the paragraph and support your argument with the details. Rely on good logic to make your paragraphs flow well.
Avoid repetition but not with the keywords. Keywords are the names of groups, variables, instruments, diseases, any specific subjects of your research — these need to be repeated and reiterated throughout the manuscript.
Avoid acronyms and try to use only well-known abbreviations.
Structure your writing process: start with prewriting, then write the first draft, and revise before you arrive at the final manuscript.
Document and layout designs are also very important aspects of technical writing. Each and every technical writer spends a considerable amount of time looking for better and more accessible ways to represent the written information because a poorly designed document can result in misunderstanding or misinterpretations. Some technical writers are allowed to outsource the design process to the design team, while others take over the documents’ design by themselves.
How to ace tech writing
First of all, no matter how techy you might be, it’s actually a great idea to obtain some sort of certification that will prove your eligibility for the position of a technical writer. Technical writing courses, while some are available for free, tend not to cost that much, and it’s an investment well-spent. Consider the following options:
- Oregon State University Technical Writing Certificate – $425
- The University of Wisconsin Eau Claire Advanced Technical Writing – $335
- Full list of other technical writing courses at UWEC
- The University of Washington Certificate in Professional Technical Writing – $3,330
- The University of Georgia – The Technical Writing Online Training Program – $1,795
- Society for Technical Communication – certification, webinars, seminars, etc.
Again, there are multiple free courses on Coursera or Udemy, so you may start there first, and then move on to the real certification program in one of the aforementioned or other accredited educational institutions.
Moreover, as a technical writer, you need to understand the importance of soft skills since you will be expected to communicate with the team members at different levels and stages of the assigned project, which might require you to come in close contact and communicate with the product owners, shareholders, top executives, developers, system administrators, and other subject-matter-experts in order to produce a valuable piece of technical content. Start working on your communication skills as soon as possible: read blog posts, master the art of public speaking, attend debate workshops, tech conferences, open up, and even try to talk to strangers. The main idea here is to get you talking.
Reading is an essential part of acquiring knowledge. Hence — read as much as possible. These are some ideas where you can get started:
- The Handbook of Technical Writing
- Managing Your Documentation Projects
- Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects
- How To Write Usable User Documentation
- Technical Writer Career Guide – Free ClickHelp Ebook
While you’re reading, start mastering instruments of documentation developing, such as MarkDown, RST, DITA, DocBook, AuthorIT.
Master the art of tech writing style. A good place to start would be the Chicago Manual of Style and Microsoft Manual of Style, as well as the timeless classic Strunk and White’s The Elements of Style.
Read as many tech documentation as you can get your hands on, and these are plenty. Look at the Iowa State University Library resources available for free for the examples of different types of technical writing from different organizations starting from NASA and ending up with the Institute of Transportation.
How to get a tech writing job
Choosing a tech writing job is an excellent idea. The demand for technical writers is always growing, and the employment growth in this field will exceed the national average for other fields due to the stable growth in science and technology. Besides, technical writing is not limited to finance, manufacturing, medicine, engineering, and computer science. Software, consulting, academia, transportation, and so on — all require technical communication specialists.
Before you embark on a journey of searching for a relevant tech writing job, you’ll need to choose your technical writing track or your area of specialization: technical, medical, and scientific. While you are getting your certificate in technical writing, consider studying and learning more about the industry you’re trying to get into. If you want to work in software development, it would be beneficial for you to acquire basic programming skills, understand the engineering process, and learn the “language” used in that field. Hone your computer skills, including popular and well-known applications such as Microsoft Office, Adobe FrameMaker, Adobe Creative, Madcap Flare, Author-it, Microsoft Visio, Lotus Notes, among others.
Subscribe to the Society for Technical Communication (STC) and join various professional groups to be aware of possible job openings and current trends in the technical writing field. Get an internship or volunteer as a junior technical writer to learn from professionals on the spot. You may do so by contacting your local STC chapter and asking if they have any volunteering projects available in your area. You may also try calling local businesses or ask your friends and ex-colleagues if they know of any company in need of a technical writer.
Contribute to open source and help open source projects get their documentation straight. Blog and write daily: write something original or try to rewrite a piece of existing technical documentation and make it better.
Become a freelance writer and build up your portfolio. At first, you may work at low-paying jobs, but as your portfolio grows, you become more and more attractive to the employers who are willing to invest in you, your knowledge, and your expertise. Try to gather at least 10 to 15 diverse examples of the best technical writing in your portfolio, make a website highlighting your best work, design your resume, and, finally, start applying for high paying jobs!
Have you worked as a technical writer? Are you trying to find a tech writing job? What difficulties have you faced in the profession? We’d love to hear your stories.
Also published on Medium.