To better understand the applications of technical writing, imagine a startup developing backup software. They process a variety of customer data and deal with a growing number of customer requests. The product has become popular and the startup is turning into a successful global company. However, they grew too fast to establish the right processes for such a vulnerable product.
Сrucial information passes through informal channels. Employees duplicate work and follow inconsistent processes. And all that creates inefficiencies and friction while increasing expenses. Another problem is processing multiple customers’ requests about how the product functions. Clients’ time is wasted and they get frustrated when looking for reliable information. All this mess is caused by the lack of established processes and can be fixed with good technical documentation.
Michael Hopwood is an in-house tech writer at Softeq. He’s been working with multiple industries, projects, and documentation types for over 20 years. In this article, he shares technical writing experience from projects he worked on.
What is Technical Writing?
Technical writing is the practice of documenting processes that help clarify project scope and simplify communication. It has come a long way from printed manuals and HTML help files. Modern examples of technical writing include API docs, markdown, microcontent for chatbots, in-app UI text, static website generation, and more.
But writing the docs is often the tip of the iceberg. Under the surface, documentation specialists are in touch with tech and business teams. Tech writers take part in building websites and testing products. They don’t just research, edit, and layout content; they also train teams to maintain their own documentation.
Depending on your project’s needs, documentation outputs may have their own focus and scope:
- Basic level: writing and/or editing content. A tech writer can jump in to create fresh content for a product in a later development stage or where documentation already exists. Their task is to follow the style, tone, voice, and templates already in place.
- Middle level: designing content, workflows, and tooling. In this situation, a tech writer contributes to a complex project where they gather required information and then structure, systemize, and unify that knowledge. They analyze the product characteristics and user needs to define the what, how, when, and why of documentation. The writer’s task is to spin up the least documentation before tweaking it to meet your expectations for look and feel.
- Advanced level: outsourced documentation team. At this level, a team of writers works best for SaaS products and complex systems with many user groups. Writers can help at the initial development stage and delivery phase, as well as over the longer term, to maintain documentation.
With professional tech writing on board, your project will get several perks. In particular, it helps you:
- Have a single point of contact for knowledge transfer
- Leverage industry-standard tools and techniques
- Develop a comprehensive technical content strategy with minimal investment
- Onboard and adapt team members
How is technical writing used? Take a look at five working use cases with real-life examples.
Use Case 1. Creating Easy-to-Understand Glossaries for Products
Keeping all project stakeholders on the same page requires some effort. For example, for users, it’s crucial to learn how to use the system without time-consuming research or having to ask and wait for an explanation. Creating easy-to-understand glossaries of terms takes time, effort, and expertise. Also, users and administrators need to know what happens if settings or configurations are changed.
Tech writers, with their expertise in research and information structuring, are here to help.
Real-Life Example: BIOS/UEFI Deployment Glossary
Lenovo has a Commercial Deployment Readiness Team. Its primary goal is to support enterprise customers who deploy numerous PCs. One element of this deployment is configuring BIOS (UEFI). Modern UEFI firmware connects with most of the PC’s hardware and operating system. That makes configuration a very complex task. The deployment team needs to quickly understand the specifics of each configuration. Before, Lenovo had all this described in separate documents.
The technical writers compiled over 100 terms into a single document. Each term was described with the following:
- Commonly used acronyms
- A full name and any alternative names
- A brief definition of the term and the system it designates
- Links to more detailed information
- Links to UEFI/BIOS settings affecting or affected by the system
Benefits
Lenovo teams can share the glossary with customers as an onboarding tool. They can also use it as a point of reference to manage internal knowledge.
Use Case 2. Developing Procedural Guides for QA and Testing
No matter how much automation expands, manual testing and quality assurance (QA) are still essential for achieving business goals. To make testing fair and transparent, they should rely on consistent, easy-to-understand practices. Such practices can also help with seamless onboarding. Here, technical writers add value through front-loading of the research and standardization. As a result, testing becomes less of a hit-or-miss operation.
Real-Life Example: AMD Benchmarking Tests
AMD wanted to measure their hardware performance with benchmarking tests. They are a set of software tests on a piece of hardware that replicate tasks performed in the real world. Benchmarking testing helps you understand how your product operates against the industry standards.
For AMD, the benchmarking tests ran specific apps, tested hardware performance, and parsed results into a usable format. Each benchmark had dependencies unique to the app. And AMD needed developers to write the test scripts and QA analysts to execute them—reliably and quickly. The tech writers helped the team test each script and recorded the process in a consistent format with explanations and screenshots.
Benefits
The company can develop new testing scripts based on the new knowledge. Also, AMD’s onboarding process for benchmarking is now simplified with technical writing.
Use Case 3. Documenting Data Design for Humans and Machines
Industries like engineering, e-commerce, and finance operate with reams of data. It’s a must for them to capture data easily and put the least effort into integrating and cleaning it up. That’s why they need to specify and document data accurately and in detail. And XML can help with this.
XML is the underlying specification for the XHTML source text used in web content, as well as for common document formats. It’s also a standard output for tech applications that need to exchange precise, structured data.
Specification writers can use XML and other markup languages to set rules for how to produce data, including its structure and type. Let’s consider a product’s price. It may only contain digits with exactly two decimal places to represent cents, and the maximum number of cents is 99. The XML definitions file (schema) can express all these requirements, making them readable by people and machines. It can therefore be used at business, functional, and tech levels to:
- Agree and confirm the business requirements
- Configure code to automatically check if those requirements are fulfilled
This also eases the need to communicate requirements to data creators, aggregating partners, and end users.
Real-Life Example: XML Schema Standards
A global standards body wanted to document their data exchange standards. The first task was to revise all documentation. The second was to align these docs with the formal validation schema, which allows rules to be created, like allowed data types for the field. Finally, they needed to bring new requirements to life.
Here’s what was developed by technical writers:
- A publication pipeline for XML Schema documentation (X(HT)ML to Word to PDF)
- Workflows for analyzing and applying new business and tech requirements
- Samples of data for tests and illustrations
- Supporting documentation like FAQs, implementation guides, and business rules to create, maintain, and update data
- Equivalent data schemas for alternative uses of the same data (e.g., JSON and CSV)
Benefits
As soon as the company standardized their approach to data, they managed to automate all data-related processes. Their data is now more consistent, reusable, and easy to integrate. Ultimately, the company was able to reduce human errors, boost data exchange between departments, and accomplish tasks with minimal resources. Documenting the data also helped them simplify regulatory compliance. As a result, the business now provides better services to its clients and has got a solid foundation for further growth.
Use Case 4. Creating Documentation That Meets the Needs of All Stakeholders
It’s a common situation when the product documentation has to cover the needs of different stakeholders. For example, consider REST API adoption in web applications. Project and product managers may need a more use-case-centric approach explaining the how and why of API adoption. For software developers, meanwhile, data-centric and often abstract guides are sufficient. Technical writers can help all of them stay on the same page.
Real-Life Examples: HTTP REST APIs
A one-stop-shop web services provider wanted to develop a standard workflow so that they could analyze, check the quality of, and publish HTTP REST API documentation. Their goal was to reduce the time from design to release and enable writers to work on more APIs at once.
Tech writers turned to the Postman generator to document an API that many of their clients used. The API has a large number of endpoints, and lots of use cases are covered as a result. It contains detailed examples and parameter descriptions in plain language for implementation managers. Developers have also obtained code samples.
Benefits
The API documentation helps the provider respond to support requests from potential implementers faster. It has also provided the baseline for future API and app development.
Use Case 5. Updating a Product Alongside its Documentation
When a product is already in use but is still being actively developed, it needs frequent updates. In such a situation, the combined practices of continuous integration and continuous delivery (CI/CD) come in handy. They allow you to update the product while customers are using it.
The product and product documentation need to be updated at the same time to keep everything in order. The CI/CD method typically employs the Docs as Code approach. This means creating and maintaining documentation as rigorously as programming code. This approach ensures the documentation source text is stored in the same repository as the code it describes. And, when each piece of code is updated, its documentation is automatically extracted to be displayed to users.
Real-Life Example: JavaScript APIs
A global web app development company with a large number of projects needed documentation for JavaScript APIs, which give access to its apps. To provide this, technical writers created a simplified backlog of requests, bugs, and updates. This enabled the company to:
- Prioritize the release of the core API functions needed by users
- Detect tech and business issues in order to refer back to development
Benefits
The company reduced the time and money wasted on bug fixes, which helped them free up developers’ resources to build new features faster. It’s also now possible to transfer API functions to users more directly and quickly. Customer satisfaction and loyalty have increased as a consequence.
Technical Writing is a Game Changer
Technical writing saves you time and money on projects and simplifies communication across the company. It also helps you leverage industry-standard tools and techniques seamlessly while speeding up development. In particular, software engineers can focus on building new features rather than fixing bugs. With better products and services, you get more satisfied customers. Tech writing services can also facilitate onboarding. Well-crafted documentation can function as a single point of knowledge transfer for new team members and help them adapt faster. All this also helps you see financial profit sooner.
