Read the Vietnamese version here.

Technical writers are born to make technical documentation much easier to understand. The complexity of modern technology and product development has led to the growth of the field of technical writing. The trend is still going strong, and there are still a lot of good chances to move up in your career or switch to being a Technical Writer.

ITviec talked to Mr. Amit Singh, a Technical Writer with 9 years of experience. He currently works at Wizeline, a leading global technology services provider that helps companies build high-quality digital products and platforms — and offers technical writing services to document these products and increase adoption.

Read on to hear Amit’s thoughts on what Technical writer does, what skills they need, and how they can grow in their job.

I. Who is a technical writer? 

A technical writer is a person who can understand complex products and technology, then communicate those technical concepts in an easy-to-understand format and language, following style guides and templates (according to Amit’s own description).

Continue from that description, there are 3 ranges of content that technical writers usually work with:

  • End-user technical documentation: User guide/ User manuals, Online-help, Installation guide, Configuration guide, Troubleshooting guide, Command line interface guide, Administration guide, API guide, Quick start/ getting started guide, release notes…
  • Project and process documentations: Project estimations, Project reports, Powerpoint presentations, Documents for training purposes, planning documents, Project templates, style guides, Onboarding guides…
  • Sales and marketing materials: Product release blogs/ articles, Marketing collaterals, Knowledge base articles, FAQs…

What does a technical writer do?

To do this job, a technical writer needs to coordinate with all the stakeholders like software developers, testers, product and project managers, sales and marketing team, and customer support team,… to gather all the required information.

Their regular works are:

  • Attending the scrums, interviewing the engineer, gathering inputs
  • Developing the document, following the topic-based authoring approach, and following the incremental model of agile methodology.

To learn more about what technical writer does, we can look at how they work with and relate to other development teams. So, why do we need a separate technical writing team when developers, QAs, and others could write technical documents instead?

Developers or QA/QCs can also write documents like user guides or release notes, but it is always recommended to have a separate entity for technical writers. 

Because engineers can only write about their own technical parts, while technical writers work on all the parts together. Not to mention that engineers are better at coding than language and grammar, while technical writers have a language background and have taken courses and gotten certifications to do the job.

Amit’s experience shows that big companies like Cisco, which has a huge content management system full of documents, should have a professional technical writing team. It brings 3 major benefits:

  1. Quality. Amit believes that “if you concentrate in only one domain, you can be more productive”. So a professional technical writer may perform writing far better than an engineer.
  2. Time and effort. With a technical writing team, all the features and functionality are well explained, and we even have video tutorials capturing all the screens. So you can receive fewer customer calls and spend less on your customer support.
  3. Trustworthiness. If all the features are documented in an authentic and legal form, the customer will have more trust and connect with your products and organizations.

II. How to develop a technical document?

Nowadays, the technical writing process requires a lot of time to research and develop. In the Agile methodology, it should be running parallelly with the development and testing within a 2-week sprint.

Fact: In 2010, things were much simpler. They used to prepare user documents in MS Word and customers received the outputs in PDF. But now we have multiple fancy output formats based on the XML author tools.

Technical writing needs a cyclical process formed in the concept of DDLC (Document Development Life Cycle). The DDLC explains the end-to-end management of technical documentation – from building from scratch to maintaining. 

4 phases of the Document Development Life Cycle:

technical-writer-1

  • Phase 1. Analysis (Researching and gathering information)

Technical writers receive some feature/ software requirements from the product owners or stakeholders (whoever are responsible for the product launch). Then they analyze the requirements and gather all the following components:

– Audience: You must know who you’re writing for. For the beginner audience, the document should cover basic features and use simple language. For the expert audience, you can add advanced features and use more technical jargon and flowery language.

– Type of Document: Before writing, you need to know what kind of document will work best. For example, Online help is the best type for a software with user interface, whereas a physical User manual is useful for hardware products.

– Tool kit: Technical writers have some tools to do the job:

  • Authoring tools: Robohelp, Framemaker, Microsoft Word…
  • Screenshots tools: Hijack Pro, SM Snap, MS paint
  • Multimedia creation tools: Camtasia Studio, Adobe Captivate…

Metrics to select the tools: Based on the type of document. For example:

– Framemaker and Microsoft Word are the best tools to create user manuals.

– Robohelp is used to create online help and web help for the application.

 

  • Phase 2: Design. In this phase, the technical writer will design:

– TOC (table of content): the initial plan, hierarchy, or architecture of the document, with page numbers for each topic.. 

– Style Guides/Style Sheets: Style guides consist of standards that help to develop consistency throughout the documentation. They define the feel & tone, also the dos and don’ts of a document.

There are many style guides available from different publications: 

– Microsoft Style of Technical Publication

– Chicago Manual of Style

– Style of elements by Shrunk & White, and more. 

Microsoft’s Style of Technical Publications (MSTP) has been considered to be the technical writer’s bible. Globally, everyone is following the MSTP. However, every company will customize the style guide based on its own product.

– Templates: A template or outline establishes the document structure, consisting of the different levels of headings, the number of tables and images in the document, and so on.

– Project Planning: The project plan is filled with every detail of the project, such as the total number of topics involved, the number of Technical Writers involved, tentative time spent in writing and reviewing, and more. 

 

  • Phase 3. Content development. 

– Writing first draft: Technical writers write the first draft with their own understanding and knowledge (based on their research work).

– Review: There is a minimum of two rounds of review to maintain the consistency and accuracy of the content:

+ Language Review: Check spelling, grammar, punctuation, and other things to make sure the language is consistent and follows the style guide. Technical writers can check on their own.

+ Technical Review: This round is to make sure the content is correct from the technical point of view. Technical writers send documents to the SME (Subject-Matter Expert) for technical review and get them to sign off. 

Who is the SME?

SME can be anyone from engineer, product owner, or QA team, who has a deep understanding of the features and acts as the contact point with customers.

Generally speaking, in Agile methodology, there is an engineering manager for particular features. That manager is the go-to person for a technical writer, called the SME.

 

  • Phase 4. Deliver & Maintain: 

The document is delivered to the client in the pre-decided format. Once the product has been released, it’s easy to update and maintain. One technical writer is enough to take care of 2-3 products when it’s already gone live.

– Maintaining: This stage is to preserve the documents for future reusability. Content Management System (CMS) like Microsoft SharePoint, Astoria, and Documentum can be used here.

 – Update: If any bug is reported by the internal team or customers, developers will fix it and discuss it with the technical writing team to define the changes in the features and functionality. Then, the technical writer will be responsible for updating all the documents.

The DDLC (Document Development Life Cycle) will be in a loop. Collaborative Process Management tools like Jira and Rally will help to manage the cycle. Senior members can develop a 2 – 16 points checklist, and the writers should mark all the points he has done like: grammar check, consistency check, style guide check, technical check…

In a simpler language, you can follow these steps to start your basic technical writing:

  • Freewrite
  • Brainstorm
  • Research/ Planning
  • Outline/ Design 
  • Draft content
  • Revise (and revise again)
  • Proofreading and editing
  • Publishing 
  • Maintenance upkeep

Principles of quality in technical writing

Amit provided some keywords for high-quality technical writing: 

  • Proper usage of grammar
  • Writing concisely
  • Use of active voice, positive and gender-neutral statements
  • Avoid long and complex sentences
  • Use punctuation correctly
  • Follow the style guides and templates
  • Follow parallelism and minimalism

In the past, everything used to be jumbled up into one single document of 100 – 200 pages, which was so confusing. Now in Agile methodology, they split it into small features and functionality. The average document length for one feature is just about 1- 2 pages. In one month, Amit’s team is supposed to develop 10 – 15 pages of technical documents for 10 features.

Technical writing vs. Content writing

Punchlines, emotions, or humor are not recommended in technical writing style guides. It’s different from content writing, blog writing, or any other marketing writing materials. 

As Amit said: “It should be straightforward instructions or commands. That’s all, no emotions, no empathy.”

Another difference is technical documentation is very “technical”, so only the audience to whom it is intended can understand, while almost anyone can understand blog content.

technical-writer-2

III. How to become a technical writer?

Any graduate with these qualifications can become a fresher technical writer:

  • Good language skills
  • Attention to details
  • Quality oriented
  • Good research and analytical skills, especially audience analysis
  • A good communicator, who can collaborate with the different teams to gather information.
  • Contribute to the collaborative work environment
  • Ownership 
  • Multitasking and project management skills while working on multiple projects simultaneously. 
  • Have the interest to dive deep to gain knowledge and understanding of the product.
  • Having a basic understanding of codes is a plus to develop API and developer docs, or can use snippets of the codes for better understanding.

And to become a senior writer, you need to work on these skills:

  • Project management
  • Multitasking
  • Working parallelly on multiple projects
  • Mentoring
  • Automating the process and work to reduce the efforts

Regarding how to improve technical writing skills, Amit also provided some general advice:

  • Get into the reading habit to enhance your grammar & language skills
  • Practice more on XML-based authoring tools
  • Collaborate with other fellow writers
  • Attend technical writing events to update the latest market trends.
  • Get certifications from technical writing-related courses
  • Practice public speaking/toastmasters

IV. Career opportunities for a technical writer

Many IT business industries have a strong demand for technical writers. Some of them are:

  • Networking and telecommunications
  • Cloud/storage
  • Semiconductors
  • Healthcare
  • Finance/banking
  • E-commerce
  • Media and entertainment
  • Industrial automation

There are two orientations that technical writers can follow in the next steps of their careers:

1. Advance to Doc managers/ Doc directors: By learning coding languages such as Java or Python and completing API certifications as well as project management certifications, you can advance to roles such as BA, project manager, product owner, or delivery manager. If you work in a large corporation, you can even aspire to be the Director/VP of documentation.

Explore more Java jobs on ITviec

Explore more Product Manager jobs on ITviec

2. Continue to be an individual contributor. The only difference is that your salary will be lower than that of someone who has advanced to the level of manager and can manage a team.

When asked about a belief that, “For a technical writer, the more you define your niche, the better your career will be,” Amit doesn’t really agree. For him, gaining expertise in a specific domain can help you excel in that domain, but it will limit your horizon. As a writer, he believes that writing is the most important aspect and that you should be prepared to write for any domain or technology. It will broaden and diversify your work.

Salary range of a technical writer

The salary range of a technical writer can be between 1500 – 6000USD/month (in Amit’s Arabic region) as an individual contributor, not in a management role.

  • For juniors at the learning stage: You can make 1000 – 1500USD as an associate if you don’t know anything about tools, products, or style guides yet.
  • For mid-levels/ seniors: You learn a lot about the technical writing process and authoring tools in 2 – 4 years to grow up, then your salary will increase.
  • The highest paid (5000 – 6000USD/month) goes to those who can understand basic codes like Python, and Java, or can read API and developer documentation. It may take 10 – 15 years for you to reach that level.

In service-based or outsourcing companies, the salary might be a little less than in product-based companies.

For the bonus, if you fulfill the requirements such as: productivity, quality, your collaboration with the other team members and your company performance, then you probably get your bonus on project-based. 

V. Materials for technical writers

1. Books for Technical writers: 

  • Wren and martin for grammar, MSTP for style guides
  • Technical Communication 12th Edition by Mike Markel
  • The Insider’s Guide to Technical Writing by Krista Van Laan
  • Technical Writing Process: The simple, five-step guide that anyone can use to create technical documents such as user guides, manuals, and procedures by Kieran Morgan
  • The Handbook of Technical Writing with 2020 APA Update 12th Edition by Gerald J. Alred, Walter E. Oliu, and Charles T. Brusaw

2. Learning courses for Technical writer

  • Basics of Technical writing
  • Coding for writers: Basic programming
  • API and developer documentations courses
  • Information architecture and Information mapping

3. Amazing Technical writers to follow:

Keith Johnson, Sandhya Ranganathan, Anu Kothari, Anupama Honamore, Suraj Pratap.

VI. Real sharings from an experienced Technical Writer

Life-changing decision in Amit’s career:

Initially, Amit started his career as a technical writer for the Aerospace domain. His job was to prepare the component maintenance manual for the aircraft. Compared to companies that make software and technology, the salary was very low. In six years, his job had not changed much, and he was ready for something new.

Then he decided to switch his career to the software domain, he realized there is a huge gap in the compensation, work-life balance, the people and the tech here. So after making that life-changing decision, he got a lot of good opportunities.

The stressful moments of a technical writer:

In Amit’s experience, the most stressful moments are mostly about communications with various stakeholders and follow-up to get the content reviewed and approved on time.

For example, in Agile, codes can sometimes be changed at the last minute. The engineer’s input is needed by the technical writer, but he is busy writing code and does not respond. So it becomes difficult and stressful to get that information.

In Amit’s case, his solution is to spend more time learning about the product. So even if the developer is busy, he will be able to at least make a draft of his own and have a quick call to review with the developer later.

Apart from that, Amit points out that it can be stressful in the startup scene. When the startup is not well funded, they don’t have the budget for a strong technical writing team. So a job of 10 people must be done with only 4 – 5 people.

However, technical writing is never stressful if you’re a quick learner who can understand the product easily and willing to research. It’s not like you are just sitting and people will give you the inputs, you have to run behind them. 

What is the failure that Amit has learned the most from?

The failure that Amit has learned the most from is in the 4th – 5th year of his career, when he was working for Automation Anywhere – an organization doing robotic process automation with the chatbot automated to reply to users’ inputs.

The development was going on, but the release was there. So Amit made up 2-3 installation steps with his own perspective, without technically verified or invalidated, then put them into the document. However, those steps were not really accurate, so the end users were not able to perform the installations.

So Amit’s lesson is “never trust your instincts”. Always go with the product specs and perform due diligence before concluding. Always go with the data, verify the information with SMEs until it’s crystal clear, as well as open for discussion before putting anything into your document, publishing, or sending it to the customer.

Otherwise, it can create trust issues between the customers and your organization.

technical-writer-3

Advice for fellow or future technical writers

  1. Understand your target audience (very important).
  2. Understand the technical level of the documents. Ex: User guides or quick start guides are not really “technical”, but just give you an overview of the product. 
  3. Have consistency, always upskill yourself and keep yourself updated with the market. 
  4. Always adhere to your company’s style guide by reviewing previous documents to reflect the similarity of tone, language, and copyright information. If one document is completely different from the others, the customer will be confused about whether it is authentic or has been copied from somewhere.

About Amit Singh

technical-writer-expertWith growing technologies and the number of technologists who create them, being a Technical Writer places you at the intersection of the technology creators and its users. This is what got Amit interested in the field of Technical Writing.

He started his journey as a technical writer in 2010 and joined Wizeline in 2021. He loves the way the company functions, the culture, and the fact that through their products they offer value to customers. In Amit’s career, he has worked in various domains such as telecom, networking, data storage, media and entertainment, robotic process automation, and e-commerce.

In his experience as a technical writer, he has worked on various kinds of end-user documents across multiple purposes and channels, such as user guides, API guides, blogs, and more.

Explore more good jobs at Wizeline