Several years ago I attended a management training course. It was largely a series of scenarios throughout which you had to apply the rules of the particular branch of management methodology to which we had ascribed.

It’s been a long time since I revisited those rules but by and large I’ve adapted them to match my personality and my own beliefs as to how a technical communications team should work. They are, as I’m sure you’ve probably realised, largely based around common sense and the knowledge that you are working with professionals. If you are not you are either working for the wrong company, or you hired the wrong people.

So, how do you hire the right person?

A quick search on the internet will return many thousands of results, featuring articles, training courses, recommendations and strategies. I’m not suggesting that my approach is better or worse than any but it’s worked well for me.

My guiding principle is not to treat an interview as an interrogation. It may sound obvious but I’ve been for interviews where you get sat across a desk from three or four interviewers who take turns in asking you very specific questions. This is fine for some roles but, particularly for technical communications, removes a lot of the value of the interview.

An interview is a conversation, during which you are trying to ascertain personality fit to your corporate culture and their abilities to fulfill the requirements of the job. The latter includes how they learn, how they communicate, how they think and plan what they are writing, as well as how they deal with challenges and adversity, and if they like pizza (an important factor in any software development office!).

That said, there is a structure that I follow and which I explain to the interviewee at the beginning.

Hiring new staff is fraught, and rightly so, as it’s likely to be the biggest ‘purchase’ you make for your company. I’ve conducted enough interviews that I’m fairly comfortable with the process, and have a good feel for when to press for more information and when to sit back and let the candidate sell themselves.

I may post more on how I conduct interviews later (anyone interested?) but as I am hiring right now I’ve started to think about the whole induction process, and how we can best get a new technical writer into the team and up to speed.

First of all there is the timing of these things. Rarely do you get the luxury of being able to streamline a new team member into the start of a release lifecycle, so you need to consider what they will be working and, possibly, whether you keep them out of the main stream of work until a new cycle begins. Like most departments we have a slew of ongoing tasks that are not directly related to new product development, and one of my favourite items to get a new start to tackle is the installation guide.

Typically, unless you are writing documentation for a very simple application, the initial setup and configuration of a product can be confusing. You may need to consider underlying platform choices, supporting applications, databases, connection protocols and so on, all of which the customer controls and which mean there isn’t often a common set of instructions.

There may be some initial configuration required before you can run the setup routine, and the choices made available may then impact what options are available later on in the process.

Ultimately it’s the trickiest thing to get right so my view is that a fresh set of eyes, belonging to someone who has yet to be inflicted with the curse of knowledge (that is, they don’t know anything about the product so don’t presume the audience will either), is ideal for reviewing and updating an installation guide.

Beyond that there are matters of tooling and procedures to be learned, as well as the general culture to be communicated and encouraged. I firmly believe the latter is the more important, tools and procedures can be learned over time, but fitting someone into an established culture, into the way we think and the way we tackle our work is far more important.

I’m about to head into a two day, brainstorming style, workshop. I was invited along as there will be a lot of useful information flying around, and it’s the beginning of a new stream of work. I will spend the next two days with the people who know most about our product and have already made it clear that my presence will be participatory, not dictationary!

I was quite adamant about this, to the point of being slightly abrasive, as it’s something that happens a little too often. Whilst they may not realise it but asking a technical writer along to “take notes” is basically asking us to sit quietly in the corner and “write stuff”. Because that’s what we do, right?

Part of me gets really annoyed when this type of thing happens, but part of me realises that I probably do the same to other professions. What we, as technical writers, consider important is not the same as that of the developers or engineers and that will never change.

I’m happy that, when I was invited to the workshop on the premise of “taking notes”, it only took a quick chat to persuade the technical architect that what he really wanted from my presence was actually the main focus of the workshop. Whilst we will be reworking (prototyping) some code, it’s not anything we can use and so the bulk of the output from the two days will be in the form of guidelines and best practice information.

And that I can help with.

Scott Nesbitt over at DMN Communications recently posted about mentoring and yes, I am quite flattered that I am mentioned…

I have been a team lead/manager at three different companies, cutting my teeth the first time as the youngest and most inexperienced member of the team at Dr. Solomon’s (the anti-virus people, bought by McAfee) standing in for a couple of months whilst a new department head was hired. Needless to say I didn’t do much mentoring there, as I was still largely learning my trade.

The second position was my best learning experience, with a small company that went through a couple of boom/bust cycles. I learnt a lot about myself, the role of technical communications within a software company and as I was hiring and building a team I spent a fair amount of time mentoring some of the technical writers I worked with.

But not all of them.

I’ve never been afraid of hiring someone with more experience, better knowledge or better skillset. Part of that is acknowledging my own weaknesses, and partly it is knowing that a good team requires the right people with a good range of complementary skills.

That said, I have worked with a few less experience technical writers and I do enjoy that process and the challenges it can bring. As I’ve recently been trying to allude, the considerations our profession requires can quite perplexing, and it’s good to talk through such things as, frequently, I too will learn something from those discussions.

So I guess what I’m trying to say is that I think that being a good mentor is as much about listening and learning as it is about guiding and teaching. I should really run this past my parents as they are both teachers and I’m sure will have a view on this kind of thing.

Today though, the role of mentor is fulfilled in a different way. We all have access (limited or otherwise) to some very very smart people in our industry, and whilst I do bemoan the noise on such places as TechWR, it’s true to say that I’ve learned a lot about what I do (and why I do it) from some of the people on that mailing list.

With that in mind it seems to me that the wisdom of the crowd is the new mentor, and that the next time someone asks us why we bother with blogs, twitter, mailing lists and so on, that that is the answer we give.

After all, everyone needs a mentor.

It’s a common topic, an oft repeated complaint, and one which has already had many many lines of advice written, and countless suggestions offered. So here’s a new slant.

The reason most technical reviews fail is because of the writer, not the reviewer.

It’s not because the reviewers couldn’t find the time, it’s not because the reviewers didn’t understand the need or reasoning behind the review, it’s not because they didn’t know what to do, and it is most certainly not because they don’t value your contribution to the product and your part in the development process.

Because, if any of the above reasons are true, it’s YOUR fault, your responsibility.

Katherine Brown covers this area well in her recent article, noting that:

reviews can often go awry for a number of reasons at a number of points in the overall process:

• Poor communication
• Lack of preparation
• Lack of management support
• Unclear expectations and objectives for the review
• Insufficient time planned for the review
• Lack of follow-up
• Wrong people involved, or right people involved at the wrong time

Katherine goes on to offer solutions to all of these issues, but I have a different slant, namely:

• Poor communication - if, as a technical author, you cannot communicate there are bigger problems than the technical review!
• Lack of preparation - you are asking reviewers to give up their time, even if it is agreed many will consider this an ‘extra’ piece of work. Not preparing for this is likely to come across as both unprofessional and arrogant. If you don’t seem to care about the review, why should they?
• Lack of management support - yes, we do need to fight a little harder to get support for our work from management. No, it isn’t the way it should be. As professionals we need to learn to promote ourselves and, by our actions, gain the support we need.
• Unclear expectations and objectives for the review - as I’ve said, many people treat reviews as an interruption, so it’s up to you to make the objectives and requirements clear. What should they be looking for? What should they report back, and how? If they have a general query how do they present it during the review?
• Insufficient time planned for the review - as a project manager once said to me, there is no such thing as “not enough time” just something called bad planning. Yes you may need to fight to get allocated time (and you should, ad-hoc reviews are never as productive as well organised and scheduled sessions) but it is an important part of the technical publications process, so fight your corner hard.
• Lack of follow-up - It’s not hard to send a short email, summarising the main review comments or outcomes, to those that were involved. This is something I am terrible at but I know, when I’ve received similar communications, how well they work and how good they make me feel.
• Wrong people involved, or right people involved at the wrong time - “The more eyes the better” doesn’t always hold true. You need to figure out the best people, and make sure they are reviewing the content at the correct time, enlisting the help of your friendly project manager if required.

This may seem harsh but, and this is something I’m guilty of myself, there can be a tendency to wrongly apportion blame, to presume that the technical reviews are failing because no-one else is interested, or presuming that the work you do doesn’t need a review anyway (and you hate to bother those busy developers, right?).

We are responsible for our work, we are responsible for the information we produce and as the technical review is part of that production process (it is NOT a QA check!) then, if it is failing… well, I’m sorry, but it’s your fault.

As part of the product, testing documentation seems like an obvious thing to do, but what does it really mean? I’ve fielded the question in a few different places now and it’s always interesting to delve deeper and understand the rationale behind the request.

“We should test the documentation”, seems like a harmless enough statement and I’ve heard it uttered in more than one place yet I’ve never worked in a company that actually tested the documentation.

Some clarification is usually required, of course, as there are many ways that you could test the documentation, for example:

• For online help, test that any hooks from the application to the documentation work properly
• Check that cross-references are corrected and, if hyperlinked, work properly
• Test the content matches exactly what is on-screen
• Test the flow of information is correct and makes sense from a users point of view

Now, we do test that our online help works correctly, that the correct page is launched from the application and that a sampling of internal links work correctly.

However, the last two items in the list can be a bit of a thornier issue. Testing the content is a much bigger job than most realise, presuming it is being done correctly and it also raises the fun issue of is this a bug in the documentation, or in the application.

Every time I’ve had this question asked I’ve said yes we should test the documentation, but what I really mean is that we should use the documentation to test the application. One method I’ve thought about is to have one person would read out the instructions, with another piloting the application. Just an idea but it would flag up some issues in both areas, I think.

Of course such resource heavy requirements rarely see the light of day and the simple fact is that we don’t test the content of our documentation. Yes we get it reviewed but they are separate (if closely related) things.

So, in an effort to close the gap between reviewing the documentation and testing the documentation, it is probably worthwhile running a short workshop for your development team, a 10 minute session that shows how best to review documentation. I’m planning such a workshop at the moment, so more on that, soon.

Anyone working in the software industry will know the term “usability” and have a reasonable idea of what it entails. As a technical writer, a user advocate within the development team, there is typically an overlap between how we think, and how usability specialists think.

For starters, anyone who is delivering information should know who their audience is and why they require the information. With a good understanding of your audience, you will know what information they require because you will understand how they use your product.

It seems obvious yet it’s something that many people struggle with, and I wonder if it is partly because, rightly, usability is a distinct field which has many experts and practitioners.

However, many software companies do not have resource dedicated to usability as, and I don’t get to say this often, it’s often seen as less of a priority than technical writing.

Why does any of this matter to you as a technical writer? Because it’s another string to your bow, another item to add to your CV, and something else that will convince your boss that it’s worthwhile keeping you in the team.

And hey, it’s interesting stuff, a little task analysis of the requirements, some creative thinking, and an even better understanding of the product and then, if you are really lucky, you get to talk directly to users of your product.

I’m part of the ad-hoc usability team in my company, and whilst it can be challenging it is part of my job I hugely enjoy and which makes me a better technical writer, and that’s never a bad thing.