Quick-start guide

I just handed over a piece of work I did for the Internet of Things (IoT) Foundation team at my company, Spark New Zealand Limited.

As part of a review of the customer journeys for one of our IoT products, I was asked to rewrite and redesign the “quick-start guide” for adding devices to a third-party portal.

Because my company doesn’t own the portal, it’s not possible to change the flow of account registration emails or anything inside the web app, like links to help topics, tool tips or UI improvements. Instead, we’re currently wrapping the help content around the third-party platform. Many customers end up emailing or calling the support team just because they forgot their password.

The existing content was a heavily highlighted Word document that was attached to a welcome email sent to all new customers. It was missing some steps, it was highly technical and it didn’t give a sense of hierarchy, in the sense that the most important information looked the same as trivial notes. I worked from this document along with the welcome email and the technical experts in the IoT team to redesign the content for web.

To organise my first draft, I mapped the content by sections to a customer journey map. We use the JUCCI framework, which stands for join, use, change, care, involve.

Then I rewrote the content within those sections to be customer-friendly, based on my own nonexistent knowledge of IoT and networks.

Finally, I did two rounds of user testing and observation using an actual field test device. When the user has followed the steps correctly, the device actually sends data to the online web app.

See it here: IoT Quick-Start Guide

Knowledge base

Soon after moving to New Zealand in 2018, I took on a short-term technical writing contract at Deane Apparel.

The project

Deane is a garment manufacturer and supplier in New Zealand and Australia. One of their key differentiators in the NZ/AU market is SILK, a uniform management system. Their clients can manage and track uniform allocations using this system.

As part of bringing this feature to the market, I created the initial technical documentation, including:

  • Release notes
  • Step-by-step guides with screenshots
  • Glossary
  • Troubleshooting
  • FAQ

The process

First, I explored the system, noting its features and options in a Microsoft Word document. I asked the development team a lot of questions at this stage.

Then I researched a few CMS solutions. The team and I agreed on Confluence because it’s integrated with Jira, which the development team already used.

In Confluence I created a new knowledge base, created templates for different kinds of pages, and started seeding the content. I used content fragments to reuse certain content across the site where necessary.

After I had documented most of the system, I conducted user testing sessions to find any potential UX issues in the knowledge base, including searching and understanding the instructions.

Finally, I sent the knowledge base for SME review to find technical inaccuracies.

One of the requirements was a customised help guide in PDF format for flagship clients. I tagged client-specific content, and created a PDF export setting in Confluence to export the content for only that client.

Before finishing my contract, I trained the team how to maintain Confluence and showed them templates they could use to add to the knowledge base as their product evolved.

See for yourself

See the knowledge base online

Or, you can download an excerpt of the user help guide as a PDF:

User help guide

The project

After studying information architecture principles for technical writing (DITA), I decided to test my knowledge by creating a user help guide where none existed. I created my guide using a free trial of ClickHelp, which I chose since it is browser-based. That meant I didn’t need any additional software or downloads. Go to the ClickHelp site

This platform is quite basic, but it suited my purposes since I wanted to be able to practice user guide documentation while demonstrating my ability to write clearly and concisely.

I created documentation for InTouch Language Inc, the phone-based English company I’m currently working with part-time. Their existing training for teachers exists in discrete documents scattered across emails, videos and various cloud drives. Not to mention, it’s not written by native English speakers.

Exhibit A: This PDF

My final version is, in fact, a draft, because I have created this independent of a team or subject matter expert. If this were more than a practice exercise, creating and maintaining user guides would be an iterative process.

Regardless, working on this project made me happy. I’d love to do more work like this in the future, especially with different platforms.

The guide exists in Word doc format and HTML. Here are some screenshots from the HTML version, which I’ve hosted on Github.

Below are some screenshots that go into more detail about the guide.

Child pages of sub-topics have breadcrumb navigation at the bottom of the page.
Child pages of sub-topics (“Comments & Evaluations”) have breadcrumb navigation at the bottom of the page.
Each sub-topic page contains a list of all the other sub-topics within that section.
Each sub-topic page (“Logging In”) contains a list of all the other sub-topics within that section (“Using the Learning Management System”).
Each topic contains a table of contents that lists all the sub-topics.
Each topic (“Using the Learning Management System”) contains a table of contents that lists all the sub-topics.
Each sub-topic contains a "mini" table of contents.
Each sub-topic (“Monthly Reports”) contains a “mini” table of contents.
On this "Discussion Topics" page, the question categories expand and collapse using accordions.
On this “Discussion Topics” page, the question categories expand and collapse.