Last night, around 3am, I woke up. I lay there in bed wondering why I’d woken up and as my mind started to churn I realised I was very very awake.

In flooded four things I’ve been thinking about for some time, all of which are related but I couldn’t quite make the connection. Last night I cracked it. Maybe.

I’m still thinking it through but here are the four items in question:

1. Single sourcing our documentation – and recent discussions with other areas of the company who could benefit from the same approach.
2. Company Information Strategy – a simple pyramid based model that allows everyone creating content to ‘map’ their audience appropriately and which should start to help with consistency of terminology and messaging.
3. Document Management – there have been some murmurings about this from a few people and it’s likely to fall into my lap.
4. Requirements gathering – we’ve recently rolled out a new process which should lead to better requirements for each project build.

All of these are tied together, and if planned properly can feed off each other. Naturally there is quite a lot involved with all of the above and I’ll be revisiting items one and two in the coming weeks.

Ohh and I’ve still to pull together a slide deck on “selling our services”, which involves all of the above and more. Once it’s ready, I’ll share it here.

Exciting times ahead.

A teeny tiny gotcha that I thought I’d mention here. I can’t find explicit mention of it in the Author-it Knowledge Center and it’s tripped me up a bit.

Quite simply, and I realise these will sound obvious, make sure everyone who is using Author-it is using the same version of Microsoft Word.

My particular scenario has my laptop running Word 2007, making changes to the template, but when publishing from a machine running Word 2003, the footers weren’t being displayed despite the AutoText entry being available in the output Word document.

Naturally I’m discovering this delightful quirk on the final day of the project as we do a final publish and check on our deliverables. And people wonder why I’m almost bald…

I honestly can’t remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that’s a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase.

It’s also been a long time since I last worked for a company that produce and printed user manuals but that’s more to do with my career path than any decisions I made within those companies.

Even now whilst we have a “documentation set” comprising several different user manuals, it’s published to PDF and made available as part of the product distribution (and also online).

So why do we still maintain this view of how information should be provided?

There is a level of comfort in having a table of contents and a structure to the information available when writing technical information. It allows you to make sure all the required information is in place, but most of the research I’ve read, and most of the anecdotal evidence I’ve heard, suggests that those lovingly created table of contents are not heavily used.

The index is another area, hell it’s another profession altogether, that we spend a lot of time crafting and rightly so as it is used by many people to navigate their way through a document.

But one thing that trumps both of these methods isn’t available in printed documents but is widely available for online information. Search.

OK, so none of what I’m saying is new, or revolutionary, far from it. Those of us who have been creating online help, regardless of the format (a lot of which was before the internet was popularised), know that if there is a search option available, it will be used.

With that in mind, and this is most definitely something we will be consulting with our users about, we are toying with the idea of dumping the index and the table of contents, making sure the content has a good set of internal reference links so users (power and novice alike) can find “paths” through the information, and switching the front page to be a Google-esque search.

Luckily we can pilot this approach whilst still producing the Javahelp, PDFs and HTML (Webhelp in Author-it terms) output so we don’t completely alienate our users. It’ll be interesting to see outcome.

Like many, I struggle at times with a common perception, one which was highlighted to me yesterday by a colleague.

Like most team leads/managers, I have a lot of tasks that aren’t purely focussed on the creation of information. I don’t do much technical writing, instead letting the guys in my team focus on that (they are better at it than me anyway) whilst I work around the edges of what they do, things like taking a document through a review with some SMEs and processing the output, or building a new output template, or proof reading some of their work.

My team and I have a good idea of what I do, even though I also get dragged into chats about other information related initiatives (document management systems being the latest). But as far as everyone else in the organisation goes, I am obviously not doing a good enough job communicating that out.

So my colleague was asking how my team were doing as we are approaching the last few weeks of this current release cycle. When I said that it was a bit tight and we were probably going to have to move some of the ‘could have’ information, he asked why and then asked what I was working on myself.

Thankfully, to answer his question I have a whiteboard directly behind me that holds all the ‘other’ stuff that technical writing teams need to think about; Product Glossary updates, creation of a Knowledge Centre, Release Notes and so on.

However the point here is that, whilst we all struggle to convey the importance of what we do (until people get to that “ahhhhh” point which most do eventually), it is in all our interests to evangelise our services. Yes this will only have direct impact within your current organisation but the ripple effect over the coming years will start to grow as people move on and take your messages with them.

It may mean that you, and your team, need to stand up in front of the whole company to ‘introduce’ themselves and what they do (same applies for lone writers!), as well as backing that up with updates and conversations with people you may not normally chat to, and I realise it’s probably not something that comes naturally to many people.

So to give you a kick start, as soon as I’ve finished it, I’ll be sharing a sanitised version of that very presentation. It’ll be focussed on a software company which is being re-introduced to that wee team they all know of, but don’t know much about. I hope it might be of some use.

Nobody really likes planning. Plans are bad in the eyes of many people, seen as a necessary evil by others and some people would rather just jump straight in and figure things out as they go along. However, if you approach them the right way, planning can provide more than just a set of deadlines. Specifically I’m talking about the type of Information Plan that is covered in Managing your Documentation Projects.

In that respect, plans are good. They help set the direction and make sure everyone knows what they need to do to get there.

Yup, plans are good. The creation of a plan usually drives discussion around the deliverables and the audience of the information.

It goes without saying then, and I’m sure you all agree that, and this is just in case you’ve missed my point, plans are good.

Unless you don’t revisit the plan throughout the project. At that point, through no fault of the plan, the plan is useless.

It’s very very easy to get sucked into the detail of your current work, understanding how to explain to users how Widget X works if you are running Component Y, and I’m as guilty of that as the next person. Revisiting your plan throughout the project will help keep you from losing sight of the woods for all those damn trees.

I have no idea what our users want.

I do know they want information, and I know they want that information to be kept up to date as our product evolves and as far as those basic needs are concerned, I’m happy that we are meeting them. Beyond that I admit I’m not really that sure.

Over the past couple of years we have plugged a lot of gaps and improved the documentation provided in key areas all whilst keeping up with new features being added to the product. We’ve moved to Author-it to give us the advantages of re-use and multi-format publishing and on the whole we’ve built a good reputation within the company.

So it’s time to take stock and look at the next area we need to improve and to do that we need to know what our users want.

On the one hand we are lucky in that we have access to a small number of them, and if we can arrange the time we can sit down with them and ask them direct questions. However there is a large portion of our audience that isn’t available to us and who we also need to converse with.

Rather than try and start up a conversation from cold, I’m thinking it would be a good idea to ask them to complete a short survey, the results of which we can discuss when appropriate.

But what to ask? In the past I’ve tried to get users to score the documentation on a number of criteria (who easy it was to find the information, if it answered their questions and so on) but that doesn’t really give much scope to start a conversation.

So I’ve been looking about for some examples and to my delight have found many. I’ll probably be picking and choosing questions from the following, but I thought I’d list them here in case anyone else finds them useful:

• Apple Logic Studio
• Solaris Developer Documentation
• Drupal Documentation Survey
• User Documentation Survey 2009

I’d also urge you all to take part in the last one, it’s relevant to us all.

Have you run user surveys? I’d love to hear your stories, successful or otherwise.