Category: Work

When I first started out in this industry I received little direction other than “make sure you check everything” so a lot of my original ideas of how I should work and what documentation should cover were largely my own. I looked at manuals for a variety of applications and took ideas from them, adapting them for my own use, initially focussing on the structure and presentation rather than the content itself. It was this approach that was my downfall.

Actually, that’s not true. Lack of understanding of my audience was my downfall but I didn’t realise that at the time. Instead I took the “ohh that’s neat” ideas from a variety of other sources and wedged them into my documentation. What that left me with was too much content, which is almost as bad as too little, with every detail about the application covered from three or four different angles, leaving the reader confused and bewildered as they tried to figure out what they SHOULD be doing rather than what they COULD.

It wasn’t until I met one of the users, by chance, and spent some time with her that I realised (some of) the error of my ways.

These days, with a better understanding of my profession and a strong understanding of our audience, I find myself writing documentation that is just enough. Am I selling the audience short? I don’t think so, and so far none of the feedback I’ve had has stated that they didn’t have enough ‘words on the page’, although that’s largely because “Just enough” doesn’t mean “this will do”. Perhaps I need to use a different phrase…

Whilst you can over-document a product and there are always edge cases of usage that you rightly shouldn’t document, consideration of how that information is constructed and delivered not only benefits the reader, but can help you meet project demands. These days everyone is being pressured to produce more and deliver it faster, so being able to tackle work in increments, delivering smaller chunks of information more frequently, with the end goal of building them into a larger unit of content can only be a good thing.

Writing “just enough” information for a given topic fits just as well in a linear writing process as it does in single source. You get similar benefits in that you can quickly flesh out the basis of a document, then revisit each area to make it more complete. The draft and review process is one which we are all familiar with, but (and I wish I could go back and tell myself this 13 years ago!) it doesn’t mean write once, review often, quite the opposite.

One of the biggest lessons I’ve learned, the hard way, is not to be afraid of writing “just enough”, as long as it truly is enough to help your users.

a.k.a Knowing when to stop

Hey, here’s a good reason for more technical writers to start blogging, it’ll cut down on the vast amounts of prose, rhetoric and general bile that seems to be clogging up some of the mailing lists to which I am subscribed.

Now, I’ve covered this topic before, but it seems my glib suggestion of “When X replies to a thread you can safely start deleting emails from it?” might actually be of use.

When I first came across such mailing lists I quickly learned just how many pedants and procrastinators our profession has, and whilst I’m keen to be grammatically correct there comes a point where the value of said conversations becomes zero.

As I’ve said before (and been shot down on before), when it comes to the very fine details of grammar the MAJORITY of readers will be unaware. As long as they get the information they require, and it reads well and contains no basic/obvious grammatical errors then so be it.

This is increasingly the case as more people come to view information as a quick fix (thanks internet!), so the amount of time spent agonising on how to punctuate that bulleted list is mostly lost on the reader as all they do is skim the list, get the bit of info they want and then sod off back to the thing they were trying to do.

Initially I wondered if this was an age thing, the younger whippersnappers (I include myself in here) coming into the profession with a differing viewpoint. Technical Writing is no longer the profession of English graduates with an engineering bent, with computer savvy new professionals coming along, fully aware of the internet and the knowledge that printed manuals are a dying example of our profession.

But I don’t think that’s truly the case, and I think the main reason TechWR-L suffers is because it lacks focus. Whilst a lot of hot air is spouted, most of it remains relevant, even if it seems off-topic. Don’t get me wrong whilst I won’t ever join the ranks of the grammerati, I do understand how important word order and phrasing to the reader.

So perhaps the main change that I see is the growing realisation that everything we do has a value, every small interaction we initiate during our working day has a value and, as I continue to understand more and more about this profession, the more I find assigning values to all my workday activities.

When I first found the technical communications mailing lists I was very keen and fairly active as, finally, I had direct access to my peers, I could communicate with people who did the same job and had the same problems, shared the same issues.

Today I find that I get more value from the shared knowledge offered by technical communications blogs, and the conversations that take place there. I’m not sure why there is such a distinct difference but I certainly sense that I get a much higher return on my investment by keeping up with industry blogs and journals than I do having to delete another off-topic thread on a mailing list.

After all, time is money!

(Ohh dear, did I really just say that? Am I really going to finish this post with such a cheesy Gordon Gecko phrase? Ohhh, apparently I am … )

Recently Daniel Brolund posted an idea around something he termed User Guide Driven Development, it’s an interesting read and, you know what, he’s almost right.

Almost.

First up you should note that Daniel works for the company that created the application he name drops in his post, Bumblebee. However his approach did ring a few bells with me, as it would sit nicely alongside my belief that, when working in an agile development environment, you have to eschew traditional writing processes and aim to grab and pillage information from wherever you can, trickling into what will become the final publication.

What I’ve realised is that by partly adopting the process suggested by Daniel we, the technical writing team, can be involved right up front and the documentation can be one of the methods used to validate the software as it is being built.

In an Agile team, the emphasis is on Test Driven Development where a chunk of work, derived from a customer story, first has acceptance tests written for it before any coding can start. The aim of the developer is to make sure his code meets the acceptance tests. In our organisation the test team provide guidance and input to what those tests should be, but the onus is on the developer to make sure they write the tests first.

So what if we slip the technical writer into the mix? Well first up we can roll up a level to the requirements gathering point and rather than one or two developers talking to the customer to capture their requirements in the form of customer stories (with the customer being the ‘sponsor’ of the requirement and not always directly a customer of the functionality, for example in the case of a sales or marketing driven stream of work) instead the technical writer will be there to capture the stories and flesh them out to an appropriate level.

From there it should be easier to break the stories down into tasks, and as we act as user advocates, those tasks should better reflect the end user. Once the tasks are in place we can write up the documentation to that level alongside the creation of the acceptance tests and, with both tests and a few paragraphs describing the aim of the functionality (how it helps meet part of the overarching customer story), and how the functionality is expected to work (how the end user will use the functionality), then we have a very powerful way of ensuring requirements are met.

As it happens on the guys in my team is already working in this sort of manner and it’s going well. Yes it’s a mind shift for both the technical writer and the development team but it appears to be paying dividends. If everyone agrees we’ll roll it out across the other areas of development.

And then, finally, I will be able to claim that my department is running development! Mwuhahahaaa!!

OK, maybe not.

P.S. I’m aware some of my colleagues read this, don’t worry I know who you are, and you will be treated fairly when my team assume power…

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.
(more…)

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.