Tag: <span>Technical Writer</span>

In the past I’ve held the following positions:

  • Technical Administrator
  • Technical Writer
  • Documentation Specialist
  • Technical Communications Manager
  • Publications Team Leader

The first three have similarities as they were all grounded in the production of technical documentation. The latter two are essentially the same thing, leading a team of technical writers producing technical information. None of the job titles I had limited me, by my thinking, in what I could and couldn’t do.

My current job title, as confirmed on my new business cards which handily arrived just AFTER I’d been to TCUK12, is Product Information Manager. I didn’t choose this but, whilst talking through my role and responsibilities recently, I realised it’s pretty accurate.

The team I’m part of does a lot more than write technical documentation. We create many different types of information, mostly recently writing more chatty article style content, and we get involved in all manner of product related discussions. We’ve also driven the creation of a developer community website, and we continue to look for new ways to improve our offering to the product and the company.

As the onus and value of information shifts, largely influenced by the web, it’s been something that we’ve actively pushed. Whilst our work is still mostly based around the production of information (albeit in increasingly different styles and formats) we are also pushing into the area of user experience.

Having to step back to explain my roles and responsibilities was something I don’t do often enough. It’s sometimes easy to forget how far things have changed and improved, and it made me realise that my new job title is more accurate than I’d realised. My team is a product focussed team.

The realisation matters not, however, and we will continue to push to improve, try new things and if those things aren’t of benefit to us we will try others. Above all we try and keep in mind that we are working on a product, and that makes it all the easier for us to have conversations with other parts of the company.

Am I a “Product Information Manager”, not quite yet I don’t think. Whilst my team do offer various types of information about the product, we don’t yet have a hooked up strategy for the entire product, and that’s where content strategy comes to play.

Regardless, it is the first time I’ve really felt like my job description represents what I actually do and, more importantly, that is suggests that there is more to come.

What’s your job title? Is it a good representation of what you do? If you could, what would you change it to?


Where do you want to be in 5 years time? Hands up everyone who has been asked that in an interview at some point (now quick, put your hand back down or your colleagues will start to stare..).

Having been in my current job for just over 3.5 years, I thought it would be interesting to look back at where I started and ahead to where I want to be, and it was at that point I realised I have a problem (well, I have many, but I’m not discussing those here, thank you very much).

The thing is, I’m not entirely sure where I want to be in 5 years time, all I know is that I don’t want to be doing the same job I’m doing today. Which is lucky as, given the continuing impact the internet has on our profession and the software industry in general, and that my company is always willing to embrace new ideas, it’s entirely unlikely that I’ll be doing exactly what I’m doing today, even if I wanted to.

Which begs the question, what WILL I be doing?

I’m not entirely sure but looking at the way a number of discrete jobs are starting to come together, I’d imagine it would be some sort of merge of Technical Writer, Information Architecture, Content Curator, Community Manager and Social Media Advocate all bundled into one, an Information Advocate Content Curation and Interaction Specialist?? (Ugh, I hate job titles).

As we continue to explore and understand how people want to access information, as well as how we can streamline our own production processes, it’s looking more and more like the traditional technical writing role is on the way out. Admittedly that might be a long slow path of evolution, particularly for the heavily regulated industries, but more and more it seems that the expectation of customers is to have access to information online, rather than in printed form. This is not a new trend, and let’s be honest, we are not exactly quick at adopting new ways of working here in the UK, but it’s certainly where I’m looking when I consider my role in the future.


Having been in a bit of a lull, I recently asked those who follow me on Twitter what I should blog about. This post is in response to a suggestion from Peter Anghelides who replied: “Blog about why you became a technical author?

Which is a good a topic as any as, like many people in this industry, I certainly didn’t set out to be a Technical Writer, far from it.

For me Technical Writing combines two of my early interests, words and technology. Growing up I read a lot, and was lucky enough that my Dad used to bring a computer home at the weekend. BBC (Acorn) Micro, and later the first Mac Plus. I’ll happily admit to crafting documents (leaflets and the like) in every single available font on one page!

When it came time to leave school, Physics was my main interest area, and looking to add a technology slant I chose a course in Electronic and Electrical Engineering. In hindsight that was a mistake but it’s not something I regret. A few years later, with University behind me, I had converted my part-time job in McDonalds to a full-time job as I cast about for a ‘real’ job!

It was my Mum who spotted an advert in the local paper from a company looking to hire a “Technical Administrator”. The role was a mixed bag of tasks, largely supporting the small development team (all 12 of them) and after successfully negotiating a short writing test about how to use a flatbed scanner, I was soon put to work, writing documentation for their application. With little or no instruction or guidance I looked to those big clunky manuals that I had sitting on my desk, and it’s no small coincidence that the documentation I produced bore a striking similarity in style and layout to that of the Adobe FrameMaker 4.5 manual.

Towards the end of my time there, in 1995 if I recall correctly, I was sent on a two-day training course on how to create HTML pages with a view of setting up a company website. And so my journey on the internet began.

Having been made redundant I moved to England to Dr.Solomons where I gained a LOT of knowledge in a short space of time, working in a well organised, well run team. Some of the lessons learned there I now find myself echoing to my current team. A brief stint running the team also made me realise that I was capable of taking that step up.

The next role relied on my web expertise (a large part of my time at Dr.Solomons was focussed around web delivery of information) and also took me into another large company (was Tetra, now owned by Sage). A different working environment, and yet more to learn.

It was during those early years of my career that I realised that I’d fallen into a wonderful world where I could, if I so wished, dip my finger into a manner of different discussions and be involved with a large variety of people in different areas of a company. I’d speak with the QA engineers about issues with the product, talk to the Product Marketing team about how the product was being sold and who was buying it, the translation team were at the next set of desks and I’ve been lucky that most of the developers I’ve worked with have all been smart, friendly and helpful individuals. Even the grumpy ones.

My first step into team management was taken with some trepididation, but I’ve always trusted my own ability to learn quickly and with a little guidance (and one awful mistake) I think I’ve a good handle on how to get the best from a team of technical writers (for the most part, let them get on with it, they are more than capable without me!) and in the past couple of years I’ve learned a lot about selling our role to the company.

I’ve been lucky, both in the decisions made about my career (not all of which I’ve had a say in with two job changes brought about through redundancy) and especially in terms of the people I’ve worked with. I’ve learned so much from my colleagues, mentors and managers that I do sometimes wonder quite how I got where I am today.

And that’s why I’m happy to say that I’m a Technical Writer*, that I work in the field of Technical Communications and I don’t see either of those things changing any time soon.

* not that I do a lot of writing these days, my official title is Technical Information Manager, read into that what you will


My name is Gordon McLean, I am a Technical Communicator* and I am proud to be a jack of all trades.

I recall once being asked to breakdown all the skills required to be a Technical Writer, and then to provide a list of daily work tasks. The list of skills was to be used as part of a skills/training matrix, and the work tasks were to be mapped to a timesheet system.

At first I concentrated solely on the Technical Writers role, but even then you need to wear a number of hats; researcher, analyst, information architect, publisher, indexer, illustrator, proof-reader, editor… ohh and writer. All of those are unique job roles in some places yet, as a Technical Writer, you need to be able to successfully take on those roles to some degree. In most software companies a large part of the job is learning the new features, and as you have access to early builds, you are frequently also playing the part of ad-hoc tester. Admittedly you are usually only testing one scenario, and that scenario is the happy path that will be documented, but a bug is a bug and that means being able to identify one, discuss it with a tester or developer, or both, and why not log it as well?

If you are documenting an API or developer toolkit then, in those instances, you frequently don the cap of novice developer, asking the questions you expect them to ask, before switching caps to presume the role of an experienced developer and wondering if the information you are providing is too simple for them to use or if, perhaps, the structure of the information needs altered.

You need to be able to talk to developers and so you need to know a little about whichever code language they are working with, that way when they mention methods, you can ask whether they mean static or instance.

None of these skills/roles are the core part of a Technical Writers job, but simply additional strings to your bow. The more you know about everything, the more value you can add, so long as you don’t let that detract from your core responsibility, to provide documentation. However, the more you know about everything, the better that documentation will be and the higher your value will soar.

Prompted by The Top 5 Reasons to be a Jack of all Trades

* Communicator/Writer/Author, pick one. I favour ‘communicator’ because I don’t always communicate through writing, sometimes through UI design, sometimes through infographics and diagrams. You get the picture (pun intended!).


Comments closed

The following is largely focussed on the software industry as that is where my experience lies.

I’ve been an on/off member of the TechWR mailing list for many years now. I dip in and out of threads depending on my current work and knowledge levels. The membership of the list is fairly wide-ranging, with people involved in all sorts of technical communication activites across many different industries. This gives any discussions around our profession and interesting slant as, by and large, the constituent parts of what it means to be a technical writer, and the daily activities involved, are somewhat tied to the industry in which they work. My experience is largely in the software world, but many of the other list members have wholly hardware-based experience, yet others work in highly regulated environments, and some flit from contract to contract, job to job.

A while ago a discussion about how our profession was changing kicked off and the range of responses was fascinating. This wasn’t a surprise of course, the list is full of passionate and intelligent people, but did have the effect of causing me to sit back and reflect a little more on what I do for a living and how, ultimately, it’s a fairly unique profession.

The discussion centred, mainly, around how the emphasis for a lot of technical writing jobs is swaying more and more towards a more integrated approach to the role and how it fits within a team than the historical basis of being heavily centred on writing. The presumption (largely being pushed by those of us in the software environments) is that the skillset a Technical Writer brings to a team extends beyond “just writing the docs”. As a customer advocate, we can (and should) influence UI design and the functionality of the product, and increasingly we are involved in the early design discussions, get hold of early builds and so on. To a small degree, today’s Technical Writer whilst retaining the core function of writing documentation, also dabbles in UI design, functional analysis, sanity testing software (note: this is not QA by any means!) and may even contribute to the software itself.

Some say that this detracts from the role for which we were hired. I disagree.

The role of product documentation is hugely important to any company and its creation will always be the core function of a technical writer. However, as companies push to reduce timescales and costs, whilst ask that productivity is increased, the idea of a closely-knit team with a shared vision becomes all the more necessary. Integrating a Technical Writer into that kind of environment means that speciality becomes less of an issue, and everyone starts doing a little bit of everything else. This extends beyond the Technical Writer, obviously, but uniquely we span the divide between technology and user (application and customer) and so can start to play a larger part in the development of the applications themselves, and also lessen the impact on our own area of expertise.

As I stated in that discussion:

I’ve always presumed that the role of technical writing isn’t really about ‘writing’ all that much (these days) and is why I’ve pushed to change job and team titles away from “writing” or “publications” to “communications”. It’s a small thing, but I think it breaks the “document monkeys” label a lot of people still have in their heads.

What this can mean is that a Technical Writer needs to have a sufficient knowledge to be able to intelligently converse with the application developers, and a good understanding of the business and user requirements that are currently being worked on. Acting as a “user proxy” in early design meetings has the double bonus of improving the application being developed (as most developers have a tendency to think in terms of functionality, rather than task) and hopefully easing the burden on the documentation as the general usability should be improved.

A bold statement perhaps, but ultimately the long-term aim is to have a better grounding in the usage of the application for which you are writing documentation. Understanding the why, and the who, as well as the how, is not a new thing of course, but contributing to the team in a “non-document” way is the real benefit.

A lot of companies still view product documentation, and the technical writers who produce it, as necessary evils to be tolerated and humoured. Most technical writers are able to constructively challenge and change that perception and I’m certainly not suggesting that anything I’ve suggested is the only way to do things. But I do believe that, in software documentation, there is a growing call for more technically technical writers, as opposed to technical writing writers. Becoming the accepted user-advocate in your development team is one path to achieving this, and I firmly believe that it will enhance both your own career and the perception of our profession.

Additional links: TechWR Mailing List.


Comments closed

Proof, if more proof were needed that keeping the user in mind when designing a product, document or website really does work.

Renewing a support contract with a client, I was asking them if the website had been beneficial and if there was anything about it that had worked well. The response wasn’t quite what I’d expected, so I can’t take full credit for this, but it’s worth bearing in mind. Amongst various comments, one stuck out:

“… and a lot of people have commented on the fact the photos aren’t ‘glossed up’, you get a real sense of the workmanship that way”

For example, if you look at this photo page you can see that the photos used were taken by the client on a small digital camera. When I received these photos I pulled them into PhotoShop and started filtering and tweaking them, but no matter what I did to them the end result was the same.

They didn’t feel “honest”.

It’s hard to elaborate on this without sounding rather twee but ultimately I liked the fact that the photos LOOKED real, they didn’t looked staged and lit like a professionals photograph. Unwittingly I was wearing my user cap and seeing things from that point of view.

I wish I could say it was a conscious decision but it wasn’t, but it does seem that after spending many years wearing many different professional caps as part of my job as a Technical Writer, I can now flit between them without even realising!

I guess there even may be a lesson here for anyone selling something online. The more “real” you can make your product appear on your website, the better. Which reminds me, I’ve got some stuff to sell on eBay, maybe a video would help?


Comments closed

Please excuse the dust, and mind your feet, I’m still tidying up. I was always told you should finish a website before launching it but, in the days of instant gratification that advice seems somewhat stilted and old-fashioned. So here it is, yes, it’s another blog.

I’ve been blogging for many years now but this is my first attempt at writing a professional blog. To make it a little bit easier on myself I’ve chosen an area in which I’m fairly well-versed – Technical Communications. I have been a Technical Writer/Author/Communicator (I’ll cover that issue another day) for over 10 years and have worked in a variety of different environments, for a variety of different companies, with different cultures and different technologies. I’ve got various articles and whitepapers written up, but largely un-published, and these days if you don’t have a blog… then you are probably out doing something more interesting!

I’ll be covering every facet of Technical Communications that I’ve stumbled across, although I’ll be steering away from discussions on grammar, spelling and english usage (others already cover that in far better style than I could).

So what will I be covering? Everything from planning and designing documents, user analysis, manipulating graphics, DITA, working on the web, document design, AuthorIT, content mapping, agile development, review processes, using the documentation, web design, writing, modular documentation, FrameMaker, editing, CSS, indexing, task analysis, single source, content management, minimalism and much more that I’ve not thought of yet.

I’m not entirely sure where this blog will take me, where it’ll end up, but it’s first step towards a bigger picture and the fruition of many years of trying to have a “professional” place on the web. Comments and discussions are encouraged, and I most certainly do not promise to always be correct. Like most people I’m still learning and trying to keep up as the scope of my profession expands and contracts, and like most I’m sure the internet will continue to play a large part in that process.

Now, if you’ll excuse me, I’ve just got another lick of paint to apply…


Comments closed