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.

As a technical writer, I often find myself bemused by the design decisions made by developers and product designers. Any time I find myself bemused by a product I tend to look towards the supporting information.

However, the technical writer also has guard against such things, as evidenced by the instruction manual I received with my new watch. The watch itself has four buttons, and like most digital watches each button will do different things in different modes.

The buttons are not labelled on the watch itself and so the instruction manual is the only place to figure out what button does what. OK, I’ll admit it, I did play with it for a while before turning to the manual at which point I became a little confused.

There are four buttons, and in the instruction manual there is a simple diagram showing that they are labelled A, B, C and D. So far so good.

However, and bear in mind this is a watch so when you look at it the cognitive suggestion is “clockwise”, the buttons are labelled in an anti-clockwise order. Now if each button only did one thing, this wouldn’t be that big a deal. Yet because of the non-intuitive way they had labelled the buttons, I continued to find myself confused as to which button to push, returning to the manual at every point to check which button was next.

This is not a flaw in the hardware (the watch) but in the instruction manual.

Why do I mention this? Two reasons:

1. We are the interface to the interface. We can break the “product” as easily as we can enhance it.
2. Making sure co-workers realise that the documentation is part of the product can be tricky, and this leaped out at me as a good example. The product suffers because the documentation is poor.

I’m pretty sure this could have been avoided if the writer had spent more time with the product as there is little better way to fully understand how a product works, than sitting down and using it yourself.

That said, it is a very nice watch…

I hope, whether you celebrate it or not, that you are having a peaceful time with you and yours, and I hope that Santa is good to you (not YOU obviously, you’ve been bad).

Have a wonderful day tomorrow, and remember that it’s all about the people you love, not the presents you get or the turkey you burn.

Merry Christmas, everyone!

Recently, Tom suggested that:
if someone can figure out how to make help whallop the user with wonder and awe, it will be the creative innovation of the century. Once we begin to establish a standard and a precedence, people’s beliefs will change from feeling that “all help is useless and unimportant” to “the help at my company is exceptionally good and useful; I will explore it more often.”

And I completely agree.

But.

Whilst he goes on to list ways in which the future of online help may expand - personalized help, feedback options, audiovisual options and such like - I think that is only one side of the coin.

While, without a doubt I could work harder to improve the content offered as online help, I think technical communicators need to expand their view a little, step back and see a bigger picture. I’ve touched on this before, and it is by no means original, but ultimately we are at a point where it is beginning to be realised that the information provided with a product is a most valuable commodity. With that in mind, the time is ripe for what Tom suggests, a new way of presenting information is surely on the cards. However I think it’s wrong to limit it to online help or documentation alone.

I’m lucky that, presently, I’m part of a company that allows the Publications Team (MUST change that name!) to be part of the softare design process. As such I can see, from inception to release, the decisions and design thoughts that go into producing our software, and I influence them as much as I can. Making the on-screen text useful is one thing, the next step is to think “task task task” during any discussions on design. Developers, rightly, take a requirement and start thinking about how THEY can implement it, yet just by repeating the “task task task” mantra I was able to get them to start thinking about how it should end up, rather than the finite possibilities of how it could be implemented.

Just to clarify, I don’t sit at my desk and chant. Instead I tend to start discussions about our software with “OK, I’m [insert user type], what am I trying to do here?”.

I’m not ramming this down anyone’s throat, but my choice of language during discussions has started to rub off, resulting in some design decisions made because they were thinking about the task the user is trying to complete, not the fact that it would need to get info from database A and publish it to form B.

In response to Tom’s post, I said:

Perhaps the radical shift is helping to address issues without presuming that people will “end up in the help”. Instead of being the last resort we should be striving to stop people having to get to that point.

That said, if they do end up in the help then yes, it should have a sufficient “wow” factor without being useless. Ultimately, make sure the information they want is findable by whatever means they choose.

Being the customer respresentative, the interface to the interface, is part of that.

I once told a Technical Support Manager that, ultimately, the aim for my team was to put his out of a job. Obviously that will never happen as the myriad of platforms, hardware, and user issues that surround every software product couldn’t ever be documented (unless development of the software had ceased, in which case I wouldn’t be working for the company).

I guess the aim for a usability team, or anyone interested in improving the user experience, is to put the documentation team out of a job. If the interface is well enough designed that the user doesn’t get stuck, and if it includes enough information in the UI to help the user make decisions, then why would they ever need documentation? Of course, similarly to the Support team scenario, documentation will be required to support the less travelled paths through the UI, to help the user who wants to do things her own way.

And that is where Tom’s suggestions come in. If we can improve the information we provide, making sure the customer experience is maintained (bettered?), then they are more likely to come back.

It took me a while to ‘get’ RSS feeds but now that I have I find myself quite happily subscribing to them, willy-nilly. I figure I’d rather have a lot of sources than not enough.

This does mean that sometimes I don’t read all the posts, but I’ve made my peace with the “Mark as Read” option in Google Reader.

Since I first posted the feed compilation I’ve added a few different sources and it’s about due an update, and here it is.

Due to the rather cumbersome way this is created I’ve not, yet, got a “what’s changed” list, but I’m working on that, I’ll post it to the feed page once it’s done.

Christmas looms large, and the days are “fair drawing in” as they say in these parts. I’m taking a couple of weeks off to relax and recharge, and no doubt to eat, drink and be (very) merry. As ever this time of year is pretty hectic, so here are few things that caught my eye over the past couple of weeks.

10 Word to avoid in your writing
A short list but the main point is to avoid gobbledygook. One of my pet peeves is the use of long words when a perfectly valid, shorter, word is available. The Plain English website has some excellent advice if you want to find out more.

No-one reads the help anyway

the next time you hear someone say, “No one reads the help anyway,” say, “Yah, no one uses Google either.”
This will lead to a puzzling follow-up question — What do you mean? I use Google all the time.
Then you say, What do you use Google for? To search for answers, solutions, and information when you have questions?

Like some of the commenters, I disagree with this a little. At a simple level it works, but there are flaws. However, as an opening gambit I think it’s a good one. It will make people stop and think, and once you have them thinking about it THEN you can explain the more subtle differences.

AuthorIT Yahoo Group Search
I’m listing this here so I don’t lose it again. Yahoo Groups are great but the search engine frequently falls over. MANY many thanks to Hamish for providing this resource, this is the kind of thing that makes the Internet great.

Building a successful web community

Do not assume that a community, particularly a successful web community, is easily built from the one ingredient of a shared interest - ensure there is also a goal or a purpose in the mix.

Very true. I know that some Technical Communicators are starting to thinking beyond user documentation, and the next step may well be to nurture online communities around your product. This article has some good tips, and I can vouch for them all having struggled to setup a Scottish Blogging site myself.

Technical Communicators and UI Design
Scott Nesbitt spotted an article about User Interface Design and a particular section caught his eye. It states that the documentation must be considered as part of the design, and Scott goes on to say:

“technical communicators need to get involved not only in the design and usability of an interface, but also how users will access documentation from within the interface.”

I couldn’t agree more with this, and recently I’ve been pushing my team to think along these lines, realising that we work with, and develop, “information” rather than “documents” meaning we need to have a greater sphere of influence.

To coin a phrase, we are the interface to the interface.

Single sourcing is good, I’m sure most of us can agree on that, but I’ve recently been wondering if perhaps DITA isn’t quite good enough?

The thing is, I’ve been looking at DITA as a solution for our single sources needs for a while now. I’ve attended conferences, read whitepapers, listened to vendors and everything else that goes with it and I’ve got a pretty good handle on things. If applied correctly the benefits you can gain are very large, although the same can be said of any other single source project, yet what seems to be consistently missing during all of these wonderfully theoretical discussions is the cost and impact of getting such a solution “applied correctly”.

A key part of planning to move to single source, of which DITA is only a part, is understanding the business needs and technological requirements of all of the content producers in your organisation. Traditionally that means Technical Communications, Training, Pre-Sales and Marketing, with perhaps other flavours to be considered depending on how your company is structured.

However, if those parts of your organisation aren’t yet ready to move, then the business case changes. At present this is the situation I’m in, so I find myself looking for a short-term (2-3 year) solution that won’t lock us in to a proprietary format and that can give us benefits as soon as possible.

Re-use is our main reason for moving to single source. We don’t (yet) localise, and there is only one other team that has any interest in re-using our content (and even then, they are likely to use it as an source of verification, not a source of content). With that in mind, and with the proviso that I’ve used it previously, we are looking at AuthorIT.

Yes it does mean we forego a lot of the power of DITA but as it will allow us to tag topics accordingly (in keeping with the DITA model) and it does have an XML DITA output option, then it shouldn’t lock us in. I’m willing to put up with a little pain further down the road to get the benefits now.

I’m still not entirely sure what else we are missing. We publish PDFs, HTML and Javahelp, all of which AuthorIT handles, and as yet we don’t have a need to dynamically publish information based on metadata. If that changes in the near future then we’ll handle it appropriately but it isn’t on anyone’s radar.

I am concerned about the versioning capabilities of AuthorIT as we maintain the last 3 versions of all our publications, but I know there are ways to achieve this in AuthorIT. I doubt it will work as well as our current system (FrameMaker files in an SVN repository) but, as is always the case, I do expect we may need to make some compromises to get ourselves moving towards single sourcing our publications. This is our main pain point and so becomes the focus for any possible solution.

DITA remains the long-term goal but, and I’ve said this before, until there is an all in one solution that is easy to rollout it remains marginalised as a viable option. Most of us need to produce some form of business case to justify such purchases and, at present, DITA is still too costly an option. I’m always happy to learn new things, and whilst I would love to be able to invest time and resource into creating and maintaining a DITA based solution, I just can’t justify it.

All of my research suggests that, rather than being a simple installation and conversion process, creating a DITA solution requires a lot of technical know-how and a not insubstantial amount of time and resource. We can handle the first, the latter is (I believe) not yet at a level which makes it cost-effective.

Ultimately, for the moment, DITA costs too much.

Do you agree? Can you prove me wrong? I’d love to hear your thoughts on this, particularly if you have implemented DITA already. I’m keen to hear just how more productive a DITA solution can be if you aren’t involved in localisation. Have you recouped your costs yet?

Perhaps DITA is only really applicable for those with large budgets and the chance to invest heavily upfront. Alas I’m not in such a position. For the moment.