Different types of documentation
As I started my internship with Holmusk, I imagined technical writers as the ‘bridge’ between designers and software developers. Technical writers note down how a product should work, what errors might occur, and what interactions a user might face. I’ve worked to document these processes over the past two months — but I also encountered bigger questions of who my audience was and why technical writing matters.
Is it true that technical writers only write for software developers? Essentially, no. Technical writing can be geared toward different audiences and take various forms. These audiences might include software developers, but also designers, compliance experts and product testers. Accordingly, a technical writer can produce different types of documentation to match their audiences’ needs. At Holmusk, I have encountered Software Requirements Specifications documents, User Stories and User Acceptance Testing documents. Navigating each of these styles gave me insight into the software development process — and, more broadly, into how the structure of a piece of writing can make all the difference.
Software Requirements Specifications
The preferred type of documentation, when writing for developers and compliance, is a Software Requirements Specifications (SRS) document. An SRS outlines the key requirements of each product feature — what should this page do? How do its sub-components interact? It also gives a high-level overview of the user flow, outlining the different user interactions and what they result in. My favourite part has been documenting error states. What does it take to trigger an error and how can it be resolved? Identifying possible errors requires methodical and logical thinking. Often, it also requires patience — sometimes, you find a new error state just when you thought you had them all covered.
SRS documents can help developers in pre-development, i.e. before a product is developed. They describe, in writing, what the designers have in mind — allowing developers to implement their vision seamlessly and remain aware of important details. Interestingly, over my internship, I mainly worked on SRS documents post-development. A post-development SRS acts as an archive, or a ’snapshot’ of a product at a point in time. It reflects the changes made to a product during the development phase. This is important, too, because it provides a platform for future product development and centralises all of a product’s information. I kept compliance as a key audience in mind — ensuring that each part of the product was accounted for and could be traced back through meticulous numbering and coding.
Ultimately, the more detail in an SRS, the better. This gives developers a clear idea of what to implement or change. It also ensures that compliance requirements are met, and facilitates all future communication about a product’s features. I found that writing SRS post-development involves a lot of detail. Since the product already exists, animations, screenshots and design choices can also be documented. I’ve enjoyed working on design platforms to reflect the current state of a product and inserting the images into my documentation. A picture is worth one thousand words, they say? Although in reality, images are meant to supplement the writing. Clarity is essential in technical writing — every word on the page should have a purpose, and every image should nicely fit into that purpose.
User Stories
Another type of documentation I was exposed to at Holmusk is User Stories. These are also written for software developers and/or compliance experts. User stories include similar details to an SRS document, but they put the focus on a product’s users. They take on the perspective of a user trying to use a product. They include personas, or fictional users who have a specific aim — this looks something like, “As a [user persona], I want [goal] so that [some reason]”. For example: “As a registered user of X app, I want to log in so that I can access my profile screen.”
Thinking of personas allows technical writers and developers to think through the eyes of an external party. What happens if the user attempts a certain action? What parts of the flow seem less intuitive to an outsider (thus guiding future product improvements)? Over my internship, I had the chance to ’translate’ some user stories into SRS documents. This allowed me to see the overlap between the two, noticing how they present similar content in a different way. Technical writers need to have a built-in awareness of who they are writing for and what perspective they are writing from, and playing with different types of documentation gave me some great insights.
User Acceptance Testing document
A third type of documentation in product development is a User Acceptance Testing (UAT) document. This is geared toward participants in a UAT test — people who go through a product’s different features and ensure they work as intended, or note down any obstacles to usability. UATs can either involve external testers or be conducted internally by the product team (including UX/UI designers, software developers, technical writers and other team members). External testers do not know beforehand how a product should work. The UAT document is their introduction to the intended flow, to all possible user interactions and to the actions that trigger success/error states.
In the case of internal testing, a UAT document might appear less essential. A product team that is testing their own product must be already familiar with its requirements. However, a UAT document can outline the testing requirements step-by-step and streamline the process, ensuring nothing is overlooked. It is also important for compliance and traceability, as it keeps track of everything that might have gone wrong and when.
I am only just working on UAT documents in the last step of my internship. This involves ‘translating’ details from SRS documents and user stories into a different, tester-centred format. Again, I’ll be shifting gears in who I’m writing for and what perspective I’m writing from.
Ultimately, writing different types of technical documentation has expanded my view of what words can do. The way a document is structured makes a big difference — even if the content remains similar across different formats. Keeping my audience in mind — whether it includes developers, compliance experts or UAT participants — gives my writing a purpose and lets me contribute a small step toward creating a seamless product.