As a technical writer for the Track-Kit™ products at STACS DNA, I find myself working in close quarters with the developers, field application specialists (FAS) and quality assurance (QA) teams. (Did I say “close quarters” in the era of COVID? Rest assured, I mean that figuratively.) Consequently, I am in a position to observe how each team approaches the development and delivery of Track-Kit for its growing client base.
The FAS consults with the client to understand their needs, the developer writes the code and the QA team tests, tests and tests again. They share the common goal of creating a product that is easy to use and that helps the user to “get ‘er done.” Over time, I have seen that not only do we share a common goal but we also share three key guiding principles that always consider the user’s perspective.
The Three Guiding Principles
When I develop a resource—such as a help guide—I strive to create something that is easy to use and that helps the user accomplish a task. To that end, I find it useful to keep the three shared guiding principles in mind as I write. To me, there is a beauty in that backdrop of shared approaches across the company. Indulge me as I share these principles and, hopefully, convince you of that beauty.
1. The user’s perspective and needs are considered during the FAS’ consultations with clients, and when developing product specifications. Developers also consider the user’s needs; when they take into account the number of clicks to complete a task or where best to input error and validation messages, for example. I use Track-Kit as I draft documentation. I put myself in the user’s position and imagine where questions might arise. Where does a kit go after any given feature is implemented? Is it possible to undo a step? Often, validation and error messages in the software point me in a helpful direction. When I trigger an error message in the software, the action leading up to that error contributes to a tip or note in the documentation. Ideally, the user is spared the pain of making that same error.
2. Simplicity is “the quality or condition of being easy to understand or do”, or so say the wise people at Oxford Languages, the provider of Google’s English dictionary. For the user, the software should feel intuitive. For the developer, simplicity means that the code is easy to debug and can be adapted to meet a future requirement. When drafting help documentation, simplicity is required to deliver the absolute minimum information the reader needs to understand the product and how to use it. The more straightforward the instructions, the easier the action seems. Sadly, this type of writing requires me to park my pretty prose at the door. Plain language prevails in user documentation. Present tense, active voice and concise sentence structure are all characteristics of plain language. Simplicity comes across in visual design as well as in the verbal content. Some questions I ask myself: Is the information best delivered as a paragraph or as bullet points or in a table? How can we make use of headings or graphic elements to best get the message across to the user?
3. Consistency requires conformity in the application of something, whether it be a grading system or software code or quality assurance approach. The user should find the same functionality in the same place on different screens. For the developer, code that is consistent is easier to automate and test. For the quality assurance team, consistency in test plans and test cases ensures that testing results can be effectively communicated to the developers. Consistency in the language and presentation of the help guide means the user can find information quickly and understand how to leverage that information when they encounter problems. When we consider user anxiety, consistency offers reassurance to the user and becomes even more valuable as it offers reassurance to the user. For the sake of being consistent and helpful to the user, I park my pretty prose AND my thesaurus at the door. Being consistent also allows me to be efficient. I don’t have to belabor how to say something because the standard is already set. Additionally, I can turn oft-repeated content into a building block that is shared across documentation. One edit to the building block will ripple through the document. This single-source authoring helps to achieve both consistency and efficiency. Consistency also impacts user experience on the visual front. Mimicking the color palette, graphics and font styles found in the software’s interface allows us to build a bridge between the product and its help documentation. Consistency is achieved and the user is, perhaps unwittingly, reassured. To give you an example, the images below will show how a new ‘skin’ for our help documentation achieved consistency across Track-Kit and its resources, while improving the user experience.
There you have it, a glimpse into the considerations that go into the making of Track-Kit documentation and how they tie-in with the product’s development. Our goals are the same even if we’re focusing on different parts of the deliverable. Together, the shared principles of prioritizing user perspectives, simplicity and consistency help create a product that truly meets users’ needs.