By Brian Harris
My name is Brian Harris and I have been a technical writer for 15 years.
If you think that sounds like I’m introducing myself at some kind of addiction recovery program, that’s not entirely accidental. When you tell somebody you’re a technical writer (or a “technical author” or a “tech comm specialist” or a “tech pubs editor” or whatever else happens to be printed on your business card), you are often met with a look of puzzlement.
We have to accept the fact that, unlike software engineers or project managers or salespeople, few people understand what technical writers actually do. That’s understandable, because our role is so varied. There isn’t really a single definition that covers the sheer range of activities technical writers may be involved with. The nature of the role and the skills required depends largely on the kinds of organization in which we work. I suggest it’s the organization that defines the role more than anything else. This is very much the case at Red Gate, the software company where I manage a team of five technical authors.
Before I go on to talk more about Red Gate and the work technical writers do there, I think it would be helpful to give a brief history of my career as a technical author to date. This potted autobiography is, I think, not just a fascinating journey through my life, but illustrates neatly the evolving role of the technical writer.
My Fascinating Life as a Technical Writer
I graduated with an English literature degree from Oxford in the middle of a very bad recession. (Not the current very bad recession, but the one before that.) After failing spectacularly as a teacher (that’s a whole other story), I ended up in dead-end, temporary, admin jobs for several years, where I specialized in photocopying, carrying files around, and trying to look busy for eight hours every day.
My final temping job was in 1999 at the National Grid payment reconciliation division on the edge of a housing estate in Nottingham. At the time, as you may have guessed from the year, they were busy doing Y2K testing on their truly ancient and creaking set of mainframe systems. After nine months of carrying some papers around and photocopying, I spoke to one of the contract testers about my career, or lack of it.
“Have you ever thought about being a technical author?” he asked me. “You’ve got some experience of working in an IT environment, and your background is in English, so you’d be a good fit.”
Putting to one side that my “experience” in an IT environment was mostly drinking tea and chatting to people whose jobs I didn’t understand, he had a point. So I decided that “technical writer” couldn’t be any worse than any of the other terrible jobs I’d unsuccessfully applied for over the years.
My first job came after I answered an advertisement for a technical writer position posted in the Guardian. (To date, it is the one and only technical writing job I have ever seen advertised in that newspaper.) The position was with a small software company housed in a mansion built in 1622 in a Hertfordshire town. I can’t remember what kind of software they built, and I’m not sure I ever did know. I was based in a dark, musty garret room at the very top of the building working alongside a senior author. My job was to write a user manual for one of the products this company sold and send it to a print shop to return as hard-copy books, which were then shipped with the software. As far as I remember, we only saw the application when it was completed and the manual was very much of the “describe every dialog and option in the interface, in order” school. I occasionally glimpsed software engineers downstairs, but I never once spoke to any of them.
My next job was for a Cambridge company who made intelligence visualization software for Interpol and other police organizations. I was still producing hard-copy manuals (in a much wider range: user guides, quick-start guides, installation guides, reference guides, training material), but now I was also writing a comprehensive set of online help topics delivered in the old-style Windows tri-pane help system. Additionally, I had to write “What’s this?” point-and-click contextual help for every dialog option.
The requirement for detailed online help meant I worked more and more closely with the development team over the years. By the time I left, I was sitting in the same part of the building as the developers, liaising with them from time to time, and even occasionally collaborating with whichever developer happened to be working on the user interface. (This company didn’t employ anyone with the specific job title of UX specialist, but they happened to have a few software engineers with experience in the field.)
Technical Writing at Red Gate
And so, finally, I joined Red Gate. There were some crucial differences about my job at Red Gate:
- Documentation for all the products was online. For years, the hot topic at tech comm conferences had been “should we make our help public on the Internet?” There was a degree of nervousness among some of the more conservative members of the technical writing community, which now seems quaint. Producing Web pages required skills I didn’t have and needed to learn quickly: designing content for viewing in browsers, CSS, SEO, Google Analytics, that kind of thing.
- Most significantly, as a technical author, I was now responsible for every piece of public-facing text in all our products: feature names, option labels, strings, dialog titles, warning messages, embedded help … everything that comes under the rather ugly term of “microcopy.” The balance of work had now moved away from writing about products to actually building them. I collaborated on all aspects of development with a UX specialist. Between us, we were responsible, with input from the rest of the team of course, for delivering the user experience. I was not just sitting near the project team but was now a fully integrated part of it.
- The emphasis was on learning about real users as much as the products or technology. We used personas, ran usability tests, watched users struggle to perform tasks in prototypes or early builds, and iterated our designs based on that feedback. I went on site visits, attended trade shows, answered forum posts, and used every channel I could think of to understand our users better.
When I think about what I do now and what I was doing in my first job, there’s no comparison. That got me thinking. As head of the tech comm function, one of my responsibilities is to recruit and train authors. The skills that authors need at Red Gate are diverse and far from obvious. It’s impossible to infer those skills from their job titles. When we advertise for a “technical author,” we have a clear picture in mind of what sort of individual we need, the attributes they should have to succeed, and the activities we expect them to do. Writing is only the beginning. The ability to absorb technical information, empathize with users, and establish a rapport with everyone on their team is just as critical as being able to write succinctly, spell, and use correct grammar. Above all, we emphasize that their job is to “help build usable software.”
Career Development for Technical Writers
In late 2013, I joined a team of full-time “functional heads” who were collectively responsible for all aspects of software development at Red Gate—coding, testing, UX, project management, and technical authoring. We quickly decided that the first thing we should tackle as a group was the issue of career development. By this point, Red Gate had transformed from a small to a medium sized company without really changing our approach toward career progression. Our CEO’s philosophy, “it’s your responsibility to manage your own career,” became accepted wisdom and an implicit tenet of the company.
As organizations like Red Gate grow, opportunities nevertheless do naturally arise. More teams meant more project managers. More staff meant more line managers. More projects meant more technical expertise. And as time progressed, plenty of people did acquire experience, wisdom, and respect. Across the company, individuals were moved into roles with more responsibility.
So it wasn’t the case that there was no career development. There were pockets of excellent practice and a lot of work had been done on improving development discussions and devising a framework for development plans. However, the plans weren’t mandatory and were not always offered or requested. Also, the onus was still very much on individuals to drive their own progress. People were given positive feedback in their one-to-ones and occasionally encouraged to write a development plan, so while on the surface all seemed healthy and we were doing some of the right things, in reality we were failing to notice that something was lacking.
In short, we realized that there just wasn’t a coherent story about “career development” we could share across the company. So we came up with a number of key aims:
- Understand the nature of the problem
Rather than conjecture or anecdote, could we gather some actual evidence? - Propose a solution
Based on the data we collected, was there a way to address the problems that might actually work? - Implement the solution
How could we roll out the changes across the organization in an effective and managed way?
Genesis of the Skills Map
Rather than disappear into an ivory tower to stroke our beards and ponder possible solutions, we had a remarkable insight. What if we actually asked people what they thought?
If we took the time to interview everybody within development, to ask candid questions about their own career and sense of progress, we’d gather some valuable data from which we might actually learn something.
So that’s what we did. It took us two weeks to speak to everybody, but it was worth it. After collating and analysing the responses, we were struck by one key finding above all: “Most people didn’t have a good understanding of all the options available to them, either for improving in the specific skills their role demands or where their career could go. This applied even to many of the people who said they were generally happy.”
In general, people didn’t care much about their job titles and few were ambitious to progress vertically into a management role, but the majority felt that feedback in one-to-one meetings with their line manager was “blandly positive” with no specific, constructive advice on what they could learn or improve.
It was obvious that people wanted help understanding how they could broaden their skills and experience. The idea of a simple visual representation of the valuable skills for each role came up in response. We came to call this diagram the “skills map.” The purpose of the skills map for Red Gate technical authors is defined as follows:
To present to authors a visual guide of the range of options that are available to them when they consider the question, “How can I progress as a technical author at Red Gate?”
The primary purpose of the skills map is to facilitate discussion about an individual author’s current strengths and future aspirations. (Note that it presents skills and areas of expertise that are most valuable to us as a company at the moment and isn’t proposed as a generic guide to technical authoring as a profession, although I hope there is a fair bit of common ground between us and the rest of the industry.)
How the Skills Map Works
The map comprises five regions. The central area contains the core skills and key competencies we expect authors to master before branching out into the other, more challenging quadrants. For new hires, we think this should take about two years. Initially, we didn’t include core skills on the map, as it was intended as a vehicle to encourage specialization and career progression, but feedback revealed that it would be helpful to be explicit about the basics so authors could understand better what was expected of them and measure their progress.
The four quadrants surrounding the central core represent very broad categories of skills and expertise, and are there primarily to encourage an individual to reflect on where their strengths and interests lie, rather than map out a focused direction of travel toward a different role or job title. These quadrants are:
- Product: product expertise, market knowledge, customer research and understanding users; individuals with a commercial bent may gravitate toward this corner.
- Project: skills that are related to how projects are run. All technical authors at Red Gate are fully integrated into cross-functional agile development teams, so these skills are all relevant, but some authors want to get their hands dirty running things and coordinating work.
- Leadership: skills related to dealing with others, such as recruiting, line managing, coaching, and evangelizing the role of authors and the company.
- Specialist: a bunch of stuff that doesn’t really fit anywhere else, including technical specialism, ownership of tools or processes, and any area of knowledge or practice where someone might be the “go-to” person in the organization.
The skills map is mainly intended to be used by line managers in personal development sessions to frame the conversation about someone’s current skills and as a springboard to discuss career development. For some people, it is a useful visualization of the fact that they are strong across a range of different areas and spread across several quadrants; it can be helpful to explicitly recognize someone as an “all-rounder.” Optionally, an individual can assign a value between 0 and 10 for each skill to represent their experience or ability, and produce a rough “heat map” showing their strengths and weaknesses across all aspects of their role.
The skills map can also help with the following:
- Planning for the future. It can be updated to reflect technical expertise or domain knowledge that we know will be useful to certain parts of the business. For example, we include HTML5 as a skill in the tech author map, which we know will become increasingly common in developing future applications. We can then encourage members of the team to train in these areas, keep track of whether we have the right mix of skills for the long term, and be confident we’re anticipating our development needs for the next few years.
- Recruitment. It can be helpful in several ways to show applicants the skills map during the interview process. It explains quite powerfully the diverse nature of the role and the kinds of skills we value; it shows the many opportunities for non-vertical career progression; and it helps candidates assess their current skillset and predilections—for example, whether they are more “project” than “product” people.
It’s still early days for us when it comes to using skills maps routinely in our company. Before we roll them out more widely, we want to make sure line managers are fully trained in using them effectively and that there is a reasonable amount of detail backing each skill. It’s all very well for an author to say that they are interested in getting better at microcopy or learning more about content management, but without any idea of what these things are or how to develop and practice them, we’re not much further forward. So we’re producing a guide to each skill, with advice on experts to talk to within Red Gate, books and articles to read, courses to attend, and examples of best practice. This is still a work in progress.
We are also planning to make the skills maps more visually appealing, and in the long run possibly interactive, so that anyone can click on a box to read a detailed definition of what that skill involves.
In the Wider Community
I started this article by writing about how people’s eyes tend to glaze over when I describe myself as a technical author. I hope I’ve explained how the role has changed in my own short career and how it varies by organization. Even at Red Gate, which in many ways has a progressive approach to software development, there are pockets of the business where the role of technical authors is poorly understood. Sadly, I still have to expend a lot more energy than I’d like convincing managers of our value and persuading some of our senior leadership team that we are a necessary and integral part of building great software. I hope the skills map will go some way to helping make that more obvious.
And in the wider profession, I’m pleased to see that the skills map has prompted discussion about our role. My hope is that by making the breadth of skills and attributes required by authors more transparent, it will help to educate thought leaders across various industries that we’re more than just writers. And maybe one day, I will confess to someone that I’m a technical writer and they’ll say, “Oh, wow, that’s cool!” in response. One day….
Brian Harris is head of the technical communications team at Red Gate Software, based in Cambridge, England. He has worked as a technical author and occasional project manager in the software industry for over 15 years.
