Work smarter, they say, so that’s what we are trying to do. In fact I’d hope that is what we are all trying to do but, like everyone else, it’s natural that once you have a process or a tool that works for you, you tend not to look about for a replacement.

If it ain’t broke, don’t fix it, they say. But sometimes you need to break things, you need to reach the point where you know that accepting some pain, and possibly a small backwards step, will benefit you in the long run. So whilst it will be a wrench to leave our FrameMaker/Webworks based system, I firmly believe it will benefit us in the long run, and by “us” I refer to both the company and the Publications team I look after.

So, with Author-it licenses received, the first steps will be taken towards a database publishing system that will make it easier for us to work with the Training department, and ultimately make it far easier to publish the information our users require. It’s the first step down a long road.

Of course we won’t actually be breaking anything, and the migration of content and our working processes will take some time, as will learning the full capabilities and limitations of our new tool, but I’m kinda excited by the entire thing. I’m convinced if we are smart about how we handle the transition it will prove beneficial and, as I work with some really smart people, I’m sure we’ll flush out further benefits as we go along.

Consider this advanced warning that, for the next few months, I’ll largely be focussing on our transition from FrameMaker to Author-it. If you have any questions along the way, please ask, I’ll answer in as much detail as I can (company sensitivities will, of course, be my censor).

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…