Contact Us

UX Research Blog

[Guest Post] 5 Tips for Writing Awesome Software Documentation

[fa icon="calendar"] Mar 10, 2014 5:30:47 AM / by Zenya Molnar

Documentation is everywhere, whether it is in the form of a user manual for a new television, an article on how to use Photoshop, or a recipe for how to bake a chocolate cream torte. As the documentation writer on the UX team at HubSpot, I write user guides that 920-192 cover all aspects of the tools in the product, from their basic functions to best practices and strategy. Through my writing adventure, I have gathered some advice for creating top-notch documentation.


1. Writing docs isn't just about writing

Even though the bulk of the work of documentation writing is actually generating content, it is important to understand the significance of the preparation that is done first. Before you can dive into writing, it’s essential to create a plan with a vision of the content. I write user guides for HubSpot’s marketing software, and each user guide contains multiple articles. So, to organize my thoughts, I create a detailed outline where I determine the titles of the articles that the user guide will contain as well as specific steps in the article. When I am ready to get cracking at the writing, I have a clear path to follow which allows me to focus entirely on LOT-950 the content of the articles. I save time while I'm writing since there is no chance of surprise.


2. Your plan might change

In the world of ever fast-changing software, be aware that you might have to make adjustments to screenshots and to the explanation of the how-to process as you are writing. Even article titles might need to be adjusted to reflect changes. Being mindful of modifications is important so that your documentation can reflect the most up-to-date software. Although you might feel set in your ways after you spend time making a detailed outline and delving into writing, it is best to be open-minded and willing to take the extra time to understand and include the changes. For instance, while working on an article about the HubSpot Contacts tool recently, I needed to retake several screenshots because the user interface had changed while I was in the midst of writing. It’s best to debut instructions for the brand new version of the product right away instead of having to edit the documentation immediately after publication.


3. Befriend user testing

Attending user tests that relate to the tool that I am documenting helps in several ways. First of all, the tests provide me with an additional way to better acquaint myself with the product. This is especially useful when I am in the process of updating a user guide with information on a new feature. User testing with the new feature exposes me to the elements that are essential to write about in the documentation. Another benefit of user testing (besides interacting with Molly and Rachel who run very effective and engaging tests) is to understand how customers think, what they have trouble with, and to see their flow as they use the product. I benefit from hearing the types of questions that the customer asks, because it gives me insight into how I can write the guide to best suit the user.


4. Get into the flow with links

The user guide content becomes much more valuable when it is closely linked to other user guide articles, blogs, and other content within (or outside of) your company. What if a person is reading an article and realizes that he or she is in an advanced stage of the guide and needs a refresher on the basics? This would be a perfect place to link back to an introductory article. I recently wrote a user guide article on the Blog tool in HubSpot where I provided the user with instructions on how to create a blog as well as some information on strategy, but I also included external links to useful resources on the HubSpot blog to give the user more guidance. Adding links to other internal articles and user guides connects all of your information to make it very accessible and give the process a flow.


5. Content is king

Most of the folks who read a user guide need help, whether it is with a specific question or the general set-up; therefore, the copy should be clear and concise to convey the message effectively. It could be the reader’s first time, or he or she might be coming in frustrated or angry. So why not make the content somewhat light to ease the reader’s irritation and to make it a positive experience, heck, maybe even fun? I like to sprinkle my documentation with a congratulatory remark here or there or light comments to reduce the dryness of a how-to manual. For example, if one step is particularly long and detailed, at the end I may say something like “Yay! You’re now ready to finish…” I would hope that this would draw the reader out of their focus for a second, fill them with relief that they’re almost done, and reenergize them to finish the article.


Zenya is the first of many guest bloggers on UX Sisters! If you're interested in writing, drop us a line.

Topics: ux

Zenya Molnar

Written by Zenya Molnar