Top

Technical Writing: More Than a Support Function

October 8, 2018

Sometimes, new technical writers might feel a bit lost. They may not be aware of all the areas in which they can contribute. The general perspective of many companies is that technical writers do not add value to the product, but are simply part of a support function. As a technical writer, this can make your life really difficult!

In this article, I’ll discuss the various ways in which you can contribute as a technical writer. I’ll also provide an overview of a general documentation process, or workflow, that you should follow, which can vary depending on whether you’re creating release-related content or improving existing content, as well as from company to company.

An effective technical writer can contribute by

  • creating release-related content
  • improving existing content
  • automating processes
  • creating videos and tutorials
  • discovering product-related issues
  • providing product-improvement suggestions
  • writing technical articles for the Web
  • improving your peers’ technical knowledge

Creating Release-Related Content

The primary responsibility of a technical writer is creating release-related content such as product documentation. This content covers the new features and functionalities the R&D (Research and Development) team develops. As a technical writer, you should get involved in your R&D team’s weekly or biweekly meetings to ensure you understand the product’s new features and functionalities and are aware of their progress. However, before attending this meeting, learn the industry’s technical jargon and acronyms, read about the basic concepts of the new features, and try to understand the ways in which competitors have implemented similar features.

Your primary contacts for any release-related tasks should be on the R&D team. Develop a good rapport with the team by providing good feedback and asking intelligent questions. You should also understand the R&D team’s priorities and what forms of cross-team communication work best for them—for example, email, personal meetings, or telephone calls. You can also contact the verification, or testing, team to learn more about the product and its new features.

You should follow the basic workflow for writing release-related content that is shown in Figure 1.

Figure 1—Workflow for writing release-related content
Workflow for writing release-related content

Improving Existing Content

Whenever you get time between releases, read the product’s existing content, be sure you understand it, and make a list of topics that need improvement.

Here are a few suggestions for improving existing content about your product:

    • Remove deprecated and redundant content.
    • Correct grammatical errors.
    • Apply your company’s style guide.
    • Add figures and workflow diagrams.
    • Add example codes.
    • Improve the flow of information across topics and chapters.
    • Restructure topics for clarity.
    • Divide lengthy topics into subtopics.
    • Highlight important features of the product.

Discuss your findings with your group’s or the company’s editor. An editor is the best person to guide you in improving the content.

As Figure 2 shows, the process for improving existing content differs somewhat from that for writing new content.

Figure 2—Workflow for improving existing content
Workflow for improving existing content

Automating Processes

In many documentation processes, technical writers do all of their work manually, which consumes a lot of time and effort. You can automate certain processes by learning scripting languages such as Perl, JavaScript, and AutoHotkey. Scripting languages can also be helpful in the process of releasing documents. Unlike software or hardware programming languages, scripting languages are easy to learn. Plus, there is a lot of information about automating documentation processes on the Web. Learning new scripting languages and operating systems such as UNIX and Linux helps you to increase your technical expertise, enabling you to better understand the work your R&D team is doing.

Creating Videos and Tutorials

Many users prefer watching videos instead of reading lengthy documentation. Create short, interesting videos to explain new or complex features. Create tutorials to explain the product’s basic workflows or how to accomplish specific tasks using the product. You could also create a video book that comprises a series of videos. Check out similar content on the Web and look for ways to refine your videos and tutorials.

Discovering Product-Related Issues

As you work on improving a product’s content, you should simultaneously work on understanding the product better. You can increase your credibility with the team by discovering issues with the product. While you can easily find issues in a GUI-based tool, finding issues in a command-line tool can be challenging. Most technical writers do not have a very technical background, so working on a UNIX-based product may seem to be a herculean task. But with consistent effort, you can succeed and will be able to create a name for yourself among other technical writers.

Providing Product-Improvement Suggestions

In your free time, try various product features, use different input patterns and observe the output, and identify ways in which you can add value. Gradually, with time and experience, you’ll get ideas for improving the product.

Here are a few areas in which you can provide help:

    • Identify product features that are not easy to use.
    • Offer to rewrite ToolTips that are difficult to comprehend or don’t make sense.
    • Call out areas in which product-generated reports don’t provide insufficient information.
    • Offer to rewrite error messages and warnings that are not descriptive or are incorrect.
    • Identify command Help text that isn’t sufficiently descriptive or is incorrect.
    • List features, commands, arguments, or options that are redundant.

Discuss your product-improvement suggestions with your marketing and R&D team.

Writing Technical Articles for the Web

Once you understand the product and your industry, write technical articles for the Web. Because you are a writer, you can better express basic concepts for your product and industry and help people to understand them. Before writing about your company’s product, be sure to get your manager’s approval. You could also write articles about the documentation process you follow or any scripts or utilities you’ve developed.

Improving Your Peers’ Technical Knowledge

Most technical writers come from a nontechnical background. To help your technical-writing peers, you can prepare an induction program for new team members to help them understand the technology, your product, and your industry. You can also learn about your division’s other products, then offer a helping hand with them.

Conclusion

Technical writing is a good field in which to work. In addition to your primary responsibility of writing, you should be ready to take up new challenges and add value to the product you’re documenting. By gaining insights on the product, you can help the company achieve its product-development targets. In a time when companies are increasingly pursuing cost-cutting initiatives, it is important that you contribute in more areas than just writing and that you become more productive. So, as a technical writer, rather than just being part of a support function, figure out ways in which you can contribute to the development of the product! 

Senior Technical Writer at Siemens PLM Software

Noida, India

Aijaz FatimaAijaz started her career as an R&D engineer, working on PCBs (Printed Circuit Boards), FPGAs (Field-Programmable Gate Arrays), and post-silicon validation. She later realized that she wanted to do some other kind of work, so now is working as a senior technical writer. Her new job not only utilizes her writing skills but also enhances her domain expertise and technical knowledge. Technical writing offers her professional growth, while encouraging her to be resourceful and innovative. Aijaz is passionate about learning new technologies, improving organizations’ existing documentation, and scripting and making videos.  Read More

Other Articles on User Assistance Design

New on UXmatters