Like most technical writing teams we are small in number. As such, monitoring and tracking both the work that needs done as well as the work that is in progress can be a challenge.

So I’m currently casting my net far and wide to find a good way to keep a handle on this so that I’m always reasonably up to speed with where we are in the grand scheme of things. Forgive me if the following isn’t particularly well delivered, as I am thinking this through as I type it up.

First things first, we need a plan. Actually we need two. One is a high level map of the documentation structure for the entire product so we always have a view of what we are writing and where it will go, and the map will include indicators about the audience so we know who we are writing for at a given time.

Then we need to plan the next batch of work inline with the development teams, estimating what new content is need and how long it will take. Alongside that is the daily churn of small bug fixes and enhancements, some of which will need to be documented, and the supported streams of older versions of the product as well.

The occasional request via email rounds out the various routes in which new items of work are generated.

I’m ignoring, for now, passing comments by colleagues (most times I’ll just email them to our team email alias to make sure we’ve captured the request).

So, project plans, topic breakdowns, bug fixes and open requests for more information. Nothing to out of the ordinary I’m sure, nothing that each and every technical writer has to deal with.

Which begs the question, how DO you deal with it all? Over to you, how do you track your work?

I’m currently scoping some work to provide a set of user guides for an application. The functionality is, mostly, split into two areas with one set for those administering the system and the other for those who use the system to complete their work.

Previously it would have been a matter of doing some task analysis, which would drive a list of topics, which would then be grouped sensibly, all the while keeping the audience of the information in mind. However, that tends to lead to an exhaustive list of topics, often leading to areas of the product that are little used.

To counteract that one thing I’ll be doing is initially limiting the scope to the production of conceptual information. Whilst some tasks will need a level of procedural steps, I’m more keen to get across the concepts and uses of the various parts of the product.

With this in mind I’m toying with the idea of using scenarios to drive the task analysis, taking the user through a few typical usage patterns and letting them learn the patterns of how the product works. It means that we are going to be relying on the design of our product (which is pretty good) to guide users appropriately through the application.

It’s a bit of a leap of faith, but is it enough? Time will tell!

I’m guessing that you don’t want to miss that landing pad because if you do you’ll end up ditched in the ocean, floating around aimlessly and with no real idea of what to do next. Can you imagine how horrifying it would be if that happened? Floating there, unable to get back to land and with who knows what swimming around underneath you…

Yet this is the predicament that many users of online help find themselves in, having strayed into the online help they have been cast into an ocean of information with no real idea of how to get back to shore. Ohhh sure, we tell ourselves that the there is an easy way to get to the information they want through our carefully crafted Table of Contents, or perhaps a more direct route can be navigated using that Index you toiled over for hours, or better yet if they use the Search functionality they’ll find what they want. Right?

And, ultimately, yes these mechanisms work. If you know how an Index is structured you can quite quickly navigate to a keyword that probably matches the information you are searching for and should, hopefully, take you almost directly to the very help topic you need. Same goes for the Table of Contents although they are a little more prescriptive and you need to know what you are looking for to be able to find it, and of course the Search will provide you with several help topics that are, probably, what you are looking for.

Meanwhile the sharks have gathered and are nibbling at your feet!

At the UA conference last year, Matthew Ellison gave a presentation on what he termed “Keystone Topics” and in the Summer edition of the ISTC Communicator magazine (again, chock full of good stuff, it’s worth the price of membership alone if you ask me) Paul Filby covers something similar, outlining how to provide “The perfect help-system landing page”.

And so, with all of that in mind that is my task today (yes, a Saturday).

The concept is simple enough. You create a single topic that will be displayed to the user when they bash our old friend the F1 button. That topic is unique to the help system and, based on context, can be used to display a smarter set of links to potentially useful information. If you have the means you could display the most commonly viewed topics or, as I’m doing, you can point to the start of several paths covering the most commonly used areas of the product.

I don’t expect to get ours right the first time round, but hopefully the concept will work. I’m including a small addition to the foot of each such topic, asking users to contact us if they have improvements. It’s only on the landing pages but I’m hoping it might drive a nice little cycle of innovation with direct feedback from the users driving the content of the landing pages in the future.

Hopefully the landing pages will give our users some where dry to stand and survey the land a little, with clear signs to help them get to where they want to go.

I’ve agreed to present at this years ISTC conference, and my topic will be blogging and technical communications. It’s a nice topic title, vague enough that I can stretch it in many ways, but specific enough that it has some natural constraints.

I’ll write up some of my thoughts here, naturally, but it’s interesting that I’m starting to see how other areas of the online world, the Web 2.0 vision of the future, are coming into play.

Case in point: Rhonda Bracey blogs about the presentation Tony Self gave, based on an article he wrote titled What if Readers Can’t Read? which I’d already read, and linked to in my monthly newsletter column for the ISTC. The premise of which is:

The fundamental shift away from traditional forms of written communication (books and documents) to new media (e-mail, social networking, collaboration spaces) is something that we as technical communicators should be attuned to. The shift is not just from paper to online media… the shift is also away from top-down, autocratic communication structures to democratic, peer-to-peer structures.

It’s an excellent, thought provoking article, whether you agree or disagree, and it’s made all the more powerful by some of the videos that Tony showed during his presentation, videos to which Rhonda has kindly provided links.

One of the videos is referenced heavily in Tony’s article so I thought I’d show it here as it’s quite a powerful message and something that should be shaping our thinking in the years to come.

Without blogging, I wouldn’t have come across this and this is a perfect example of why blogging can be so powerful, however you do need to be part of this online conversation to be able to catch these snippets.

It’s safe to say that I’m fully hooked into the Web 2.0 world. I manage my email, calendar and task list online, as well as write and share the occasional document. I blog (in three places), I twitter, and I follow a wide swathe of information via RSS feeds. If the internet disappeared overnight I’d be lost, for any time I think ‘information’ I think internet, I don’t think book, or library, or even online help. I think internet.

This is even more prevalent when I’m looking for a solution, an answer to my current burning issue. At that point I’m looking for information from my peers, from other users or anyone else who has had, and solved, a similar problem, and nine times out of ten I’ll turn to the internet to search for that information.

Whilst such answers can be hard to track down, it feels productive to be searching for the specific answer to my specific issue, even if that takes some time and effort on my part. Once I’ve found an answer I’ll usually do a little bit of double checking – perhaps others have added a comment to say that it worked for them – and then I’m happy to accept that it is correct, knowing that if it’s not I can always head back to Google and start again. Caveats apply here, of course, depending on the severity of the issue I’m dealing with.

My point is that I freely trust the information I find based on some cursory checks, I am fully hooked into the Web 2.0 world and believe in the wisdom of the crowd (thankfully I have evidence of this as well, it’s not all hearsay).

Providing information and answers is a key part of our job as technical communicators but I am concerned that my view of the information world and how I use it may be tainting my thoughts. Do the people who use the information we produce really want to ‘just google’ for information? Am I projecting the way I think and work onto the people who use our documentation?

The obvious answer is to ask those people, and I’m in the fairly lucky position that I can do just that. A large portion of our documentation is used by our own staff, so I have direct access to my audience. So, obviously, I should just ask them: “How would you like to access the documentation?”

But I think that’s the wrong question.

Whilst it will be useful to hear the answers to that question, it is far too open ended and, to repeat an old adage, ‘the customer doesn’t always know what the customer wants’. Instead I need to figure out what the most common usage scenario is and work from that, before presenting a limited set of choices from which the audience can make an informed decision.

One thing is certain, the way I access information, the way I think about how information is structured and presented, from my professional background and my knowledge of some of the information design theories that are in use, is very different from the way I use information in my day to day life. The more I find myself leaning towards more ad-hoc, random and casual sources of information, the more I begin to wonder if the world of the professionally written and presented technical communications needs to change tack and find a comfortable middle ground, embracing all that is good about the web 2.0 internet.

Social media works because it is based on people and the availability of information (and metadata about that information). It seems all too obvious that the world of technical communications needs to make bigger strides in that direction. Many technical writers have started that journey, and whilst it means yet another set of skills that you’ll need to learn, ultimately it means that the technical information you produce will be more valuable in the longer term.

As well as my full-time job, in my spare time I also design and build websites. It’s something which fits well with my skillset as a technical communicator, and allows me an insight into the world of development as well and has mirrored my career every step of the way.

The first company I worked for sent me on a training course to learn how to create web pages and, since then (13 years ago), I’ve continued to follow the trends and techniques involved. I’ve been through using tables for layout, to the introduction of frames, the launch of Internet Explorer and the first release of CSS.

The parallels between the theories of technical communications and those of web design are very similar, the key aim is to keep the audience in mind at all times. The way you structure and present the information is also important, as is a sense of usability of the content itself.

I’ve been lucky enough to have a fairly constant stream of web design work, largely by word of mouth, and have just finished chatting with another potential client. Part of my approach is to ask to have a questionnaire filled in, largely to help me understand the requirements for the website, as well as to have something to focus the initial conversations around.

Two of those questions are:

1. Who will be using your website? What is the intended/current audience?
2. Does your current website meet the needs of your audience? If not, why not?

Which, as I’m sure many of you will already have realised, is exactly the kind of questions we, as technical communicators, should be asking ourselves on a regular basis.

I don’t like making presumptions, something that I learned early on in my technical writing career, but I am going to presume that anyone who reads this knows that they should be planning what content they produce before they start writing. You do, right?

A basic information plan will include knowledge about the audience, the main areas of the information that need to be covered for the project/release, as well as outlining the purpose of the documentation and any media and design considerations. Finally you’ll most likely provide a definitive list of deliverables, be they printed documents, PDFs or online help.

It’s this last area that I’m currently working on.

Our product has undergone some exciting changes, and the previous set of documentation was both very document-centric and , in my opinion, badly structured. We are shifting more towards a ‘traditional’ SDK approach and as such a lot of the existing documentation needs to be adapted accordingly.

Thankfully it’s largely an exercise in restructuring the documentation rather than completely rewriting anything, but it still warrants discussion with the audience as to how best to present the information they require. In that respect I’m lucky to have direct access to a representative portion of the intended audience as the bulk of the audience will be our own staff.

The functionality available in our development kit is broken into sections, with the documentation split along similar lines, and as such whilst the information in the current documentation is fine, it no longer makes sense to have it structured that way. Breaking down all of the documentation into smaller, more manageable chunks, before deciding how best to piece them back together is the current focus.

Thankfully, in preparation for our move towards single source, we had already audited our content and so, if nothing else, I have all the discrete sections of each of the current documents already list in a ‘management friendly’ spreadsheet.

So, with a bit of manipulation I can easily mockup a sample set of information topics, and then figure out how best to present them to the audience, be it PDF, online help, or via the web.

Once we’ve got a good idea of our final deliverables, I’ll run them past a sample of the intended audience to make sure they are both what is required and to set the expectation of what we are, and aren’t, delivering. Hopefully, gaining buy-in to our plan as early as possible will mean the information we provided is better received and may even start further discusssions around future improvements.