Documenting the tools you use – ASTC 2017
I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.
Swapnil Ogale presented a session titled How do you document the tools you use? His presentation was about being a technical writer on a product that you also use.
A quick look at some tools with good docs
These are the tools Swapnil uses regularly, for both business and personal use:
- Pocketbook (an expense budgeting tool)
All the above products provide a decent set of documentation and tutorials. Swapnil gave us a quick overview of the help/documentation systems provided by each tool. In some cases, he said, the documentation was easier to use than the actual product.
Introducing rounded (a software application)
Swapnil also uses a software application called rounded, and has contributed to the documentation for the application. Rounded is an accounting tool designed and built by Australian freelancers and sole traders.
When Swapnil started using rounded, he found that there was no documentation, and some of the UI was a little confusing. So he got in touch with the company and offered his help. They hadn’t considered the need for documentation up to that point.
Experiencing rounded as a customer
Swapnil talked about his initial experiences as a product user:
- He didn’t know what to expect from the product. Up to that point, he’d been using a collection of spreadsheets for accounting. He was looking for something to make things easier.
- It wasn’t clear why he should use the product.
- He needed an overview of features that would help make his freelancing life easier. Timetracking was the number one feature he was looking for. Another was reporting.
- He wanted to know if the product supported automation, such as breaking his work into smaller elements of time.
Luckily, rounded did cover all his needs. He had some questions though, and he thought it was likely other users had the same questions. Hence his offer to create the docs.
The client brief that rounded gave to Swapnil was:
Create content that describes how to use the product, is simple to read and understand, and makes it easy for new users to learn the product.
They needed something that was a simple as spoken language, rather than technical.
Swapnil created an information plan (just one or two pages describing expectations and deliverables). He created a design prototype in the form of a wireframe, using a tool called Pencil.
The early workflow: To draft the documentation, he used Gitbook. When the client was satisfied with the drafted content, they copied it and pasted it into WordPress, and used WordPress as their publishing platform.
The current workflow: Swapnil uses Google Docs to draft content, which makes commenting and reviews easy. Then the client copies the content and publishes it to Intercom.
The ongoing story of the docs
When Swapnil first created the docs, he documented his own workflow and use case. Then he needed to think about how other customers were using the product and what their needs were. To find the answers, he looked at some customer feedback. Some of the feedback was useful, but some of it was way off topic. Next, he talked to the analytics team. They had useful data on the way recent changes in the UI had changed customers’ approach to the product.
The customer requested a change in voice and tone of the content. They wanted a more conversational language, and Swapnil did his best to satisfy that requirement.
Another request from rounded was to add the “so what” factor. The docs should help customers understand why they should do something. For example, why would you want to create an invoice. Look at real customer examples to provide relevant content. Swapnil recommends that you tell a story when creating the docs.
Thank you Swapnil for an interesting look at a tech writer’s experiences as both a customer and a documenter.