Falling into Technical Writing is something a lot of us can probably relate to. Technical writing certainly wasn't a career choice I had in mind when I left university. Mind you, is it any wonder with a degree in accountancy and computer science that I ended up working for a company making software for accountants?
I've worked for Sage ever since I left university. Firstly as a developer, then as a project manager, and now as a technical writer. But none of this was part of a career plan. At times it felt like I wasn't making any decisions about my career and was merely getting dragged along for the ride. But after finally edging into a technical writing job, I found I was good at it, and have been doing this for six years. I've spent that time writing Getting Started Guides, and Installation Guides, and F1 help, and Release Notes and all the rest of it.
But, times are changing and recently I've come to realise that this job is changing. All fired up on this epiphany, I decided to take matters into my own hands and make sure I stayed relevant.
But, before I could do that, Project Dave happened.
Project Dave
We've developed a new software module for customers that's going to have a big impact on our customers and support teams.But, why so difficult?
- This was going to affect a lot of existing customers.
- The software worked very differently to what our customers were used to.
- It introduced new concepts that were difficult to understand. The primary one being the iXBRL reporting standard adopted by HMRC.
- Strong competitors would be looking for any weakness in our offering.
In short, the product had to work, it had to be supportable, and it had to be easy to learn.
A project kicked-off with the aims of rolling out this module; minimising impact on our support team; and ensuring the best experience for our customers.
Initially, I was flattered that a manager recommended me for this project, only later asking myself whether that meant I was considered less fundamental to the development effort. Whatever it meant, this was a lucky thing for the Project Dave team, because I discovered I did actually have some useful skills.
How have I stepped outside my comfort zone?
Comfort zones are great aren't they? I've spent the last six years cocooned in a world of help files and style guides and PDFs. But, maybe comfort zones can become little jail cells as well. I'd got very comfortable in my technical writing role and rarely lifted my head above the parapets to see what else was happening in the company.I was nervous stepping into that first Project Dave meeting. There were about a dozen people from across the business. I knew some of them, but I hadn't worked with them before, and I didn't know what was expected of me. Also, being honest, I was nervous about being landed with a load of work.
I still had my day job after all: writing the help file for this new module.
So, with a team made up from all across the business, we agreed to meet weekly to start this roll-out project.
The right words
What did I have to offer this team? I didn't know much about any part of the business outside R&D (Research and Development). But, in our very first meeting, someone announced that the aim of the project was to migrate our existing customers to a new product. The word migrate struck me as having negative connotations in the software business. Customers generally don't like being migrated from one product to another, so I proposed we use the word 'adoption' instead. And thinking more on it, the word 'migration' wasn't that accurate as we weren't proposing our customers stop using their existing software.Maybe some in that meeting thought I was being pernickety, but if they did, they didn't voice it. What happened was from then on we used the word 'adoption' in all our communications with customers. Precision in language is one of our skills as technical writers, and we should encourage others to see its importance. A small victory then, but it gave me masses of confidence.
Coming up with a plan
On the face of it, we had loads of time to get our customers using the new module. But, after the initial comfort of believing we had twenty-one months until the HMRC deadline, the reality was, that with a tight development schedule, we only had about nine months to get our customers ready.A comprehensive plan was a crucial part of the project. Over the years, I've learnt to become a great planner. If I didn't plan and tie in with the different projects I work on, I'd be overloaded. stuffed. I doubt I'm the only technical author who feels that constant pull in the directions of different projects and demands on their time. Technical authors are great planners. If we weren't, we'd be stuck as soon as the next project came along. So, contributing to a business-wide plan wasn't that difficult.
Hand-in-hand with planning is our ability to estimate effectively. Developers certainly have it tough when they have to estimate off the back of fuzzy requirements. But we've got to anticipate how much help their unfinished software is going to need, and try to guess how hard it's going to be for us to get our heads around the solution so we can write about it.
Planning and estimating are so vital to technical authors because we're often fitting in our work close to release deadlines, when the software is stable enough for us to play with.
Getting ready for the new module
Customers needed to understand a lot about the new module so they could start using it in their businesses. For example, although we were trying to make it simple by plugging a new module into their existing software, there was a good chance that when they got the installation disk, they'd just assume it was a regular update, and pay it no attention.By the second week of Project Dave, I was seconded into a sub-team called the 'Need to know' team.
It was our challenge to shape these initial messages. We needed to get customers engaged with us and with our plans. As a team we agreed that I'd produce a guide for this new module.
This document needed to do several things:
- It needed to explain that this update was different.
- It needed to explain about XBRL.
- It needed to encourage them to start educating their staff about the release.
It wasn't anything like the typical guides I'd write: it was more a hybrid marketing and technical piece.
This guide saw the start of some decent collaboration with product managers, marketing, support, training, R&D, all contributing to this guide. Once everyone had contributed, I used my language skills to shape this into something simple enough for the customer to understand.
The Learning Centre
One of my biggest contributions to the project was the Learning Centre.Our help is delivered in CHM files that are installed on each workstation locally. This of course means that if we want to update our help, we have to wait for the next release of the software. I wanted us to get more into the online space to free us from release cycles and react faster to customer needs.
But creating a new help centre was not feasible for this project, so with no development time available, I suggested a simpler website where we could at least host videos and PDFs. I didn't even know how to get that off the ground but after working with our marketing team, the idea developed and we soon ended up with the Learning Centre website. It didn't cost us much, and was designed in such a way that I could produce material and with the marketing team's help, get new content to customers.
Besides its primary use for customers, it was a great resource to point our staff at to get them briefed on the new module.
Roadshow planning
We knew it was going to be difficult to get all our customers using the new software in the timescales we'd like. Roadshow events had worked well in getting customers engaged previously, so we thought they could help with this project. But what did I know about roadshow planning? Unsurprisingly little. But, all I needed to do was use my problem solving skills and I was able to contribute.One problem we needed to tackle was an environmental one. We didn't want to waste printed material at these events, so I suggested we put recycle bins at the exits like cinemas do for 3D glasses. Might not be a great idea, but at least I was able to contribute. All I needed was to use my common sense and draw parallels to other problems that already had solutions. The lesson I learnt here was that it is so important to get past that fear of making suggestions in areas that don't relate to your specific role.
Usability testing
As technical writers, we're so close to our products that we should be great user proxies. I know when I'm writing a topic if I'm struggling because I'm having an off day or the process is clunky. But one thing was limiting my ability to speak with authority for our users; I hadn't spoken to a single customer in six years.An opportunity came about to get involved with usability testing on the new project and I took it. The first session was done remotely, and the second in the user's place of work. On both occasions, I got to watch a user perform real tasks with the software I was trying to document. This was pretty eye-opening. Some things I'd assumed would be simple for a customer ended up being frustrating. This taught me that I need to get more involved in the development process from an earlier stage.
One of these usability sessions highlighted another skill we take for granted. The customer had noticed a spelling mistake in one of the software's reports. This totally dented his confidence in the program and he told us he was now wondering what else was wrong with the software. Technical Authors are great at spotting spelling mistakes, and this largely taken for granted skill, on this occasion, had a demonstrable impact on the customer.
Shaping external communications
I worked closely with the team on external communications to customers, and I learnt loads from doing this. Working closely with our marketing team on a communication was enjoyable. They have a great grasp of language, take time to make sure it's right, and they're receptive to feedback. I thought we were very alike.I was also involved with the script our managing director would use in a webcast to our customer base. I reviewed it and made suggestions. It was crucial to get the tone of this right and make it seem as natural as possible. When I'd finished taking out unnecessary jargon, we had a script that was a great example of plain English.
Reviewing
Of course, it wasn't just me that would be writing user assistance for the new module. People from support, professional services, and the learning and development team would all be writing material.I've seen work from these areas before, but sometimes when I review their work, I find stuff that other people miss. In short, technical authors are great at reviewing.
For one particular course, I reviewed the training manual that would go to print for our roadshows. Overall, it was a solid piece of work and did a good job in exploring the main areas of the new module to customers. But, there were issues with it. I was the fourth person to review, and changes had already been made based on the initial reviewers' feedback. But, when I came to review, I found missing words, typos, text alignment issues etc. Reviewers should be catching these things, but they didn't.
Is this because of a lack of reviewing technique? Are reviewers too polite? Do they not give these things enough time? Possibly. I know the reviewers cared, but I don't think that reviewing was their strongest skill. However, technical authors are great at this, and we can help teach others how important reviewing is.
Has this experience changed me?
I wouldn't have been able to contribute to any of these pieces of work without stepping out of my comfort zone. I used to think I was of most use to the business in settling down and doing what was asked of me - writing help files - doing them well, and on time. But, I took a risk and agreed to join a project away from R&D.And I've learnt and achieved a lot.
What am I going to do next?
So, with all this going on what am I going to focus on next? Well, Project Dave is going to be continuing throughout the year and next, so I'll be working with that team for the foreseeable future.As well as that, there are some other things that are happening that will continue to take me away from writing help files.
There are roadshows where I can talk to customers and demonstrate the software I've been working on.
I'm getting together with other user assistance writers in the business to start collaborating. We've started meeting now, and looking at how we can share best practice. I've been sitting with some of our support team, and reviewing articles they've written for our knowledge base system. This coaching has been really well received. We're going to be focusing on video production next, aiming to agree some standards on style.
My line manager, Chris, is a usability specialist in R&D, and a couple of years ago he suggested we teach our R&D staff about the Sage tone of voice and how that applies to our user interface in the software. Chris came up with a great workshop format and we present these together. He asked me to be involved as language is a vital component in the Sage tone of voice. So, we talk about how the messaging in the software is so important to users and how we can make it better. We held four sessions last year and expect to hold more this year. Our aim is to get everyone in our R&D department through the workshop. I've done one of these on my own, and it was a lot of fun. The attendees listened, and seemed to get a lot from the session.
Our learning and development team are focused on helping our people develop their skills and knowledge. They've recently put together a great website with a growing list of resources for our staff to learn from. But, they've been asking for volunteers to help produce some of this content. I've said yes as it's a good use of my skills. And beyond even that, I'm now the learning and development champion for our R&D team in Manchester.
