Ever get the feeling that no-one reads your documentation? It’s a frequent issue amongst Technical Writers and the general stance reflects the approach many take to make sure that, when someone finally picks up the documentation, they can get to the information they need as quickly as possible.

Given that, there is little worse than to have errors reported in your documentation. After all, if they’ve only just started using it to help them solve a problem and one of the first things they spot is an error then it’s understandable that confidence drops and that they are less likely to go to the documentation in the future.

Of course we all do the very best job we can, yet the fact remains that mistakes happen, errors occur. The reason that this tends to be a bigger issue for information is down to how we process the knowledge we have.

Without getting into too much detail, learning is a continuous process and most of that happens when you are doing things, using the tools at your disposal and figuring out how they work and how they help you achieve what you are trying to complete. By the time you decide to check the documentation, you’ve (usually) got a good bank of knowledge already, and it’s building all the time.

So, when the documentation is wrong (regardless of whether the reader spots the mistake immediately or only realises it after trying out the instructions) it seems to be an obvious mistake. After all, if I can figure out how to do X, why is the documentation wrong for Y, it’s just the same process?

Software applications that have minor errors in them are tolerated because they are the tool and sometimes there isn’t an alternative. You learn how to accomodate those errors in the application and work around them. You can’t do that with documentation, it’s either right or wrong (ambiguous documentation is presumed wrong) so confidence in the rest of the information is linked to those initial few instances of usage.

We all have review procedures that should capture errors in the documentation, we do our best to think about how the user will be interacting with the product and base the structure and content of our documentation on that information, and we all receive that email that says “On page XY of the User Guide, it states that…” and our hearts drop a little.

However I think we should embrace those moments, be positive about them! You have a user who cares enough about the documentation to complain and I think it’s worthwhile thanking them for pointing out the error, tell them that it will get fixed, and encourage them to continue to let you know if they spot anything else.

So next time you get one of those emails, or a bug in the documentation is raised, be sure to follow up with the user and thank them. They are proving that people do RTFM.

Deliverables are dead. Long live multi-format, anytime, anywhere delivery of information!

The more I think about it, the more I am beginning to see that creating content, writing and styling and planning, for “print” is no longer valid.

Quick caveat: Know your audience and the requirements. Many places mandate printed documentation in one format or another. I am purely talking about my own experience in a software environment.

I’m the first to admit that whenever I start thinking about updating a manual I think in print terms. I think of entire chapters of information, I think of how the user will be able to navigate and understand the layout and construction of the document. Changing those habits is proving hard but I’m slowly getting there.

Part of that change has come about by focussing on the information types we are going to be using as the building blocks of our single source system. Making each topic unique and complete within itself requires some thought and planning, and with that planning being focused on tasks, you soon get a simple outline of the required documentation including the type of information that you’ll be writing for each chunk.

As that realisation begins to sink in, the possibilities of re-use suddenly make themselves clear. It becomes a simple matter of drag and drop to create an entirely new manual, and a new delivery method becomes a simple matter of publishing to a new format.

The latter fits nicely with some current thoughts around how we get our technical information to our customers. Whilst I don’t think Author-IT would be the best solution, or at least the complete solution, I can see us focussing more on a web-based delivery of information, pulling other available content (from mailing lists and wiki pages) into an MSDN-like community website. Add in a blog and some interaction and it could very well be the shape of things to come.

As I’ve mentioned before, for a lot of people in the software industry, the internet is THE source of information. So rather than try and force how we want the information to be delivered (maintaining legacy documentation) I’m looking at how we can deliver something our customers will use, without succumbing to the Web 2.0 crazies. Yes it could have a blog, but does it need one? Yes we could use Twitter to provide ‘from the floor’ thoughts from the development group but who would sanitise them first!

Wikifying the doc set (to borrow a phrase) is a possibility of course, but that would only be part of this solution, and would have to include the ability to package it up as a different deliverable (PDF for example) so the information can be accessed when the internet isn’t available, a requirement of our documentation.

There are other considerations of course, all of which are still being thought through and will need discussion and buy-in.

Exciting times ahead I think. More on this as it develops.

Matt Haughey is, amongst bloggers, pretty well known and respected. He recently wrote up his thoughts on weblog applications and, as they mirror some of my thinking, I thought I’d expand on this theme here.

The title of the post, Bottom line, all weblog apps suck in some way, was borne of frustration and outlines a few points which, reading between the lines, boil down to the same kind of thing.

Few web applications are at the point they could be considered a product.

Matt talks specifically about weblog applications, one of which I use to power this site (WordPress). I do a little web design in my spare time (there’s an oxymoron if ever I heard one) and have a similar working pattern as Matt; create template then drop in the code required by the weblog application, then tweak, tweak, tweak. I share his bemusement at the way Movable Type is configured, and I definitely agree with him when he says:

My ideal blog engine company would hire some seasoned blogger and technical writer to be a documentation czar, keeping docs up to date when new versions are launched, produce screencasts for introductory users, and provide complete documentation at a stable URL that applies to every version of the product. If an outside site does a better job of collecting and offering templates, a documentation leader should recognize that and link to them in highly visible places. There doesn’t seem to be anyone internal at these companies fighting for the users to make sure they can keep being informed about how to best use the product.

All of my knowledge of WordPress, Blogger and Movable Type (three of the biggest weblog applications) comes from tinkering about in the code, trial and error, and random Google searches. Sometimes those searches will take me to the website of the application, but more often than not they take me elsewhere to someone who has solved my problem already, or has a good solution that could be adapted to meet my requirements.

The information is a far more important to me than the weblog application, particularly as most of those meet my requirements and, as I’ve mentioned elsewhere on this website, the supporting information becomes the differentiator which will sway me one way or the other.

Let me repeat what I said previously:

Quite simply, products include documentation, support and training, and tell a cohesive story to a potential user. A story that says, yes this product will do X, Y and Z, and if it breaks we’ll do our best to help fix it, and we’ll support you as you learn to use it throughout the lifetime of your relationship with the product (and, therefore, the company).

The really good thing about this situation is that there is an opening here, a wide gaping hole into which a willing technical writer could leap. Most of the weblog applications are open source and would welcome you with open arms. The role Matt outlines is a huge one, but is perfectly within the reach of most technical writers. You know, if I had any spare time I might just try to get involved…

Revisiting an old post over on the Cherryleaf blog, where Ellis was prompted to ask “Can technical authors be part of ‘the conversation’ in the connected Web 2.0 world that’s emerging?” (excuse the paraphrasing).

As a long-term blogger, and someone who believes that there are many tools in the Web 2.0 world that can and should be embraced by technical communicators, I immediately started thinking about this. It’s taken until now for me to distill my rambling thoughts into something coherent. Mainly because it’s a fairly open-ended topic, and because his post includes several questions:

1. If we are going to be part of the conversation, will we be let in?
2. What would make people do that?
3. Once we are in the conversation how can we best add value to that conversation?
4. Will engaging with a community in a social networking environment create a new and better way of providing user assistance?
5. Will social networks create an opportunity for technical communicators to eavesdrop a conversation as well as take part of it?
6. Will the rise of streaming websites both for audio and video such as YouTube enable technical communicators to be more viral in their efforts to provide effective user assistance?
7. Will technical communicators see snippets of their technical information embedded in other people’s Web pages?
8. Might the lines between technical support and technical authors start to cross over?

I left a comment on the Cherryleaf blog, which I’ll expand on here, but the jist was that I think Technical Communicators are (can be, should be) the social web of the workplace.

However, I guess we first need to understand what we mean when we refer to the “the conversation in the connected Web 2.0 world”. The fact that you are reading this blog suggests that you are already au fait with the Web 2.0 world, and are probably familiar with the popular commenting system most blogs have. That is one part of the conversation, a direct dialogue with the author and with others who have an opinion on the current topic. Now, take that conversation, expand it on your own blog, mention it in your Facebook, add a publically shared link to your del.icio.us account, or even link to it using Twitter… all of those expand the conversation by increasing the audience. There are other examples but you get the gist, the Web 2.0 world allows multiple discussions, centred around one conversation, to take place in different places, with different people and provides them ALL with a way to find out what everyone else is saying.

Needless to say, information is the key component of these discussions, and it is at this point that you realise just how valuable that information has become. Because information is now passed around, diluted, distilled and deconstructed, then rebuilt, reposted and reworked, in multiple places by multiple people with multiple aims, then the person who is central to that information becomes a V.I.P. indeed.

Whether we like it or not, our primary role SHOULD become information guardians. That will mean less writing, and more knowledge/information management and architecture. It will mean a shifting of skill sets towards new areas, where there is no best practise only gut feel, and the embracing of openness. Information will still need to be filtered, focussed and published, but once you’ve set it free, you’ll also need to nurture it as it develops. The delivery of information, naturally, becomes paramount.

We are the ONLY people (in the IT space) that can fill this role properly, and so getting a foot on the rung now will stand us in good stead. Embracing Web 2.0, and thinking about content rather than documents is a small step but a vital one.

So, let’s revisit those questions:

1. If we are going to be part of the conversation, will we be let in?
   Why are we waiting for an invite? Perhaps the future of technical communications models itself on sales and marketing rather than the technical departments. If WE want this, WE need to grab it.
2. What would make people do that?
   Convincing others of the growing value of information is paramount. Those that get it will embrace the change and happily let us push the conversation forward, those that don’t will flounder.
3. Once we are in the conversation how can we best add value to that conversation?
   By monitoring it, gently tweaking it, and making sure it has a useful life, wherever it is. This may mean collaborating with your competitors, it may mean sourcing information externally, but as long as you remember that the conversation is a big value-add to the information, then you won’t go far wrong.
4. Will engaging with a community in a social networking environment create a new and better way of providing user assistance?
   Yes. How can it not? Is it better to lock away your information, leave the users to stumble around for their own solutions and create a distrust of the information you provide, or be open, honest and provide assistance as and where needed, realising the value, power and benefits of having a thriving user community?
5. Will social networks create an opportunity for technical communicators to eavesdrop a conversation as well as take part of it?
   Yes and no. Yes, you will be able to eavesdrop but I’d encourage that to only be used in the “monitoring” sense. Get involved, ask your own questions, post your own thoughts.
6. Will the rise of streaming websites both for audio and video such as YouTube enable technical communicators to be more viral in their efforts to provide effective user assistance?
   Possibly. I would argue that information shouldn’t be viral but expected. However, it may be a useful way of raising awareness and kick starting the conversation in the first place.
7. Will technical communicators see snippets of their technical information embedded in other people’s Web pages?
   Yes. Why not? It’s not “your” technical information really, it’s information for the uses of your product. In fact, if you DON’T see this happening then the conversation is failing.
8. Might the lines between technical support and technical authors start to cross over?
   Yes. There are already signs that this is happening. Ultimately, a conversation friendly company won’t care WHO is doing the talking, as long as the conversation is taking place.

There does seem to be a trend in our profession to expect things to happen a certain way, only for them to pass us by in favour of others. Ellis makes the point that Technical Communicators should’ve been more involved during the rise of Intranets, yet that never happened. The same may be happening already, with the Web 2.0 conversation already taking place. Yes, that’s right. Somewhere, people are already talking about you and your product. It may be on their blog, in a Wiki or forum, or maybe it’s all hidden away in emails and instant messages. Regardless, the conversation has already started.

So go and find these people, get to know them, make friends, chat a little. Understand what they want, find out what they are discussing and contribute.

Join the conversation.

Audience, audience, audience.

A simple mantra, and one which crops up in most technical writing discussions at some point. If you don’t know your audience then how do you know what to write, and why you are writing it?

Most technical writers will be aware of the particular audience for the document they are working on, but as part of understanding WHO the audience is, we must also have some knowledge of WHAT they do, or don’t, know. But how far can presumption take us? If we don’t have access to our users to perform a thorough user analysis then we are, at best, guessing. Even if it is in a very well-educated way.

Of course understanding WHY someone is using your documentation goes a fair way to providing a basic framework upon which you can base further “guesstimates” as to what information your readers require.

With this in mind, I have long since used the following general presumptions. I will stress that they are no replacement to actually talking to users, but they can help focus early discussions in a project.

My suggestion is that there are at least six key phases, or touching points, during which a customer will be interacting with your company and the information you provide. Touching points are not always direct, may not always be pushed out to the customer, and they may not always be followed in a linear fashion, as they are entirely dependant on the needs of the user.

Naturally the specific Touching Points within your interactions with customers will differ, but it’s a good exercise to step back and make sure you’ve captured them.

First Touching Point
The first time a customer hears about your company. This may be because:

• They have a pressing business need and their research brought them to your website.
• They attended a Trade Show, and received your marketing literature.
• You are following up on a potential sales lead from another project.
• They received a recommendation from a colleague.
• They have worked with you before.

The information requirement at this point is largely high level and business focussed. It’s more than likely that the information will be consumed by senior management, or perhaps used by middle-management as part of a briefing to senior management.

Second Touching Point
The customer is aware of your company and your products, and has a basic understanding of what is offered. They are looking for more information to allow them to make the necessary business decisions: Will this product meet our business need? Does this product offer a good ROI? Is our business ready to adopt this product? Does this product meet the regulatory requirements our company operates within?

The information requirement remains business rather than technically focussed, but has some aspect of product documentation available, an overview of the product capabilities and the underlying requirements and prerequisites.

Third Touching Point
By now the customer has decided that your product is viable for use within their business. You need to make sure they are fully aware of the implications of purchase, and of any additional requirements that their specific needs may drive.

They need to raise a business case and start the purchasing process.

Largely driven by Sales, the information here may be pulled from a common pool, with the prerequisites driving the information itself.

Fourth Touching Point
The customer has bought the product, and the deployment phase has begun.

For a custom solution, the bulk of the information needs to flow through a deployment or solutions team, as well as being usable by the customer throughout the lifespan of the product. This touching point is key during this stage as a lot of the information you will provide at source is likely to be edited to match customer needs. For an out of the box product, the information is centred around product functionality.

Fifth Touching Point
The product is deployed on the customer site. You are now in the support phase, and the need to be able to handle usage questions and more advanced requests for specific information.

Information requirement is largely customer driven but may still be pulled from various ad-hoc forums and FAQs.

Sixth Touching Point
The customer is transitioning from one version of your product to the next, or between products.

As a starting point, I think this approach is valid, and I’d be interested to hear if you have made similar assumptions. I wonder how often we document products without any insight into the audience whatsoever, and if you have done so, I’d love to hear how you tackled it.

Prompted by two recent articles discussing the use of a Wiki, firstly this one by Joann Hackos, and this excellent followup by Ann Gentle, I realised that my current place of employment is an excellent example of how well a Wiki can work internally, and how we are considering building on that success by creating an externally available source.

I can take no credit in the fact that the development team I currently work within has, and actively uses, a Wiki. I joined the company in January this year, and was delighted to find such a resource not only available, but being actively populated.

As an internal resource, the technical advantages of using a Wiki to capture technical information are fairly obvious. The ease of use, and open nature of a Wiki suit the task very well and I think it’s fairly safe to say that a lot of developers enjoy the lack of structure and formality as well. However, it’s one thing to have a Wiki, quite another to make it a central resource that is used without much, or any, prompting.

The key is to make the Wiki THE central resource for team specific information. With that in mind, most of our meeting minutes are posted there, as are seating plans, high-level feature plans and so on. Detail is kept to a minimum, and as they are using the Wiki to track their own work, it’s a simple next step for them to start populating it with any useful nuggets of information.

As for using a Wiki externally, I think Joann has the right idea. If you have a complex product, that can be used in many different ways and scenarios then, quite simply, you aren’t going to be able to document them all. It’s also likely that your users are going to have their own ideas and thoughts and, in some cases, your users may take matters into their own hands and start populating some form of resource of their own.

Wikis, forums and so on, considered the hubs of the social web, have shifted the power of information from the traditional model. Information is now considered free, and regardless of your view on whether or not that is true, the social web and, more importantly, the people involved within it, will pursue whatever they need to meet their needs. So, if you aren’t meeting them, and there may be valid reasons as to why that is so, as I mentioned previously, then perhaps part of our role in the equation is to become the faciliator in that area.

Of course, building an online community, regardless of how it is maintained, is no easy task. The beauty of a Wiki is that it is largely self-administrating, and you can rest assured that your users will automatically be predisposed to making it as useful as possible.

Creating and providing a Wiki to external users has an element of risk, and the biggest challenge may be convincing all the areas within your organisation that need to buy-in to the idea.

Do you use Wikis, internally or externally? Do you have a company blog? An online forum? If so, I’d love to hear your thoughts and experiences.

Additional info: How to hold meetings on a Wiki

Like most people, I ‘fell’ into the world of Technical Communications. I didn’t choose this career, and like many I didn’t study anything that remotely involved writing. But then, who really knows what they want to be when they are choosing what to study at university.

So, after spending a few years learning about Electronic and Electrical Engineering, and largely finding the entire experience boring, I packed that in and somehow found myself working as a Technical Administrator for a small local software firm. My Mother had spotted the job advert in the local paper and the rest, as they say, has passed under the bridge…

Having spent some time helping out at a local community centre, creating flyers and brochures for local charities and organisations, starting work as a Technical Author was a departure into a new ‘technical’ world. I learned a lot of things in that first job but the most important things can be easily summarised and stated that as “how NOT to be a good Technical Author”. Still, no-one can say I don’t learn from my mistakes.

Fast forward many years and I find myself in the position of knowing enough about my profession to understand how it can best help the company for which I’m currently working, and being comfortable enough about the processes involved with being a Technical Author that I don’t need to worry about them on a daily basis. I can quite happily paddle along, with nary a ripple cast in my wake. Of course I strive keep up-to-date with the latest fads and fashions in the world of information access and creation, technologies and methods which are constantly on the move, but the changes to the prevalent methodologies within the Technical Communications industry (the draft and review process for example) evolve rather slowly, and I have to admit that the lack of speed of progress in these areas is a concern.

Anyone involved with the software industry will have felt the varying effects of the internet, good and bad, as it has ripped across many different areas of technology, massively changing how people think about information. We, as Technical Authors/Writers/Communicators now work with a commodity which continues to rise in value as more and more people create and manipulate, publish and expose it for everyone to use. It’s no revelation to state that the internet has brought about an ‘information boom’ and this boom means that, for those of us working in the software industry, we need to rise and meet one simple expectation.

I want it now. No, I don’t want to look it up. No, I don’t want to have to read anything. No, I’m not that interested in anything else other than solving my current problem. Now. Please. Thank You.

Not even 10 years ago the expectation was different. The expectation had some built-in tolerance, an acceptance that information may need to be found, or at least filtered, from at least one source. Maybe that expectation was taken advantage of, maybe that expectation gave us an excuse to produce a level of product documentation that was ‘good enough’, as opposed to ‘better than expected’. Maybe not.

The field of Technical Communications prides itself on making information usable. Yes, there is a focus on making sure that information is complete, and accurate, but after that there is little point in having information if what the reader wants to find is hidden away behind some weird structure or methodology with which they are unfamiliar. There are a number of ways to presenting information to the user, and some consistent methods such as a Table of Contents, or an Index being the most common. However these all require some effort and in the age of instant access I’d humbly suggest that there is one growing universal truth by which all information must abide: If I can’t Google for it, why would I bother?

Of course it’s not all bad, one technological advantage of the “Google-age” is the relative lack of work required to make your information available to the mighty search engine. Put your PDFs, web pages, or even Word documents on a website and Google will find it. Simple enough.

However, to fully leverage the advantage and properly embrace the webcentric view so many people now have of the information world, we, as a profession, need to add another string to our bow, we need to master the skill of search engine optimisation (SEO). This is no small task but, naturally, the internet is brimming with information that can help, with plenty of hints and tips to get you started.

The world of information, both creation and usage, continues to change, I wonder what other skills we will need to develop?