The boom of the internet is better documented elsewhere but the one key and founding principles is the ability to converse with anyone, anywhere in the globe. From the early days of IRC and email, onto graphical websites and instant messaging through to the current swathe of, for want of a better phrase, Web 2.0 services.

Twitter, blogs, social bookmarking, and online communities are the current rage but, do they work?

I’m a member of several email lists, swapping emails with a large number of people on a range of topics. I spend a fair amount of time filtering out topics which don’t interest me, and over time I’ve come to recognise various people by name. However email, whilst great for sharing information, is a limited when it comes to building communities.

Understanding who you are conversing with and the additional interests they have helps build trust, helps build better conversations and helps build communities. Transferring that kind of interaction online means we can better leverage shared experiences and hopefully make it easier to find other people with the same, unique, slice of knowledge and interests.

It’s only now, pulling together all the available technologies that such online communities are possible.

And the good news is that we, as technical communicators (content professionals) now have such a community.

Scott Abel, aka the Content Wrangler, has launched the Content Wrangler Community website and, having signed up and started using it a little I have to say that it is well worth a look. There are already several hundred members (825 at present), and these early adopters have started forming focussed groups, all of which relate back to our profession. In the words of the website:

Network with peers. Find jobs. Share information. Start a blog. Upload and watch videos. Join a group. Begin a discussion. Learn about software. Find events. Ask for help. It’s all here. Become a member. It’s free!

It’s safe to say that “social networks” aren’t everyone’s cup of tea, but I’d strongly urge you to check it out. Despite only having been launched a couple of weeks ago, it’s already proving popular and, as the conversations start and people start to find clever ways of using the various features available then it’s only going to get better and better.

Visit the Content Wrangler Community website today, sign up and join in!

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…

What of agile documentation?

It seems like such an old argument that surely, SURELY, doesn’t need revisiting? Alas it seems that the world of software engineering still contains those who think that code = product. Thankfully, in my experience, the numbers are thinning as most practitioners of modern software practices are at least educationally aware of the need for product documentation, even if they don’t fully understand the reasons. However, there are still those who are happy to hack away, and then claim they have a product. If you are such a person let me make one thing clear, you are wrong.

Not only are you wrong but as time marches on, you get further and further from being correct, all the while creating further problems for you and your product.

Just over a year ago, in preparation for my new job, I spent sometime reading up on Agile development and in particular I focussed on Extreme Programming (XP). The more I read the more I came to realise that this was an area which was popular with developers, yet had little to no mention of product documentation as a fundamental part of the methodology.

Mention of unit and acceptance testing as fundamental parts of working in XP suggested there was at least an understanding of the importance of solid, well constructed tests to help make to a “better” application (test-driven development) but the more I read, the more I become slightly disconcerted at the lack of consideration given both to the production of product (end user) documentation or of the benefits and skills a technical writer can bring to a development team.

Truth be told, I’ve still to find more than a passing reference in any of the more recent publications and articles I’ve found but I’m happy to be proven wrong. Perhaps I’ve been reading the wrong things, and visiting the wrong websites? Or, more worryingly, perhaps there really isn’t anything out there.

Obviously, as a technical writer, the role of product documentation as part of the product is something that is at the forefront of my mind, and I’m not expecting any software engineer to have to worry about such things beyond understanding that we are a fundamental part of the product offering and hopefully agreeing that there is a level of expectation setting to be undertaken.

That said, I do expect a software engineer to understand that software without any support, be it formal documentation, training, or a dedicated support team, is NOT a product. If we can’t agree that fundamental trait then perhaps that problem requires a solution (thankfully, as I said earlier, I don’t think it’s a huge issue at present).

Quite simply, products include documentation, support and training, and tell a cohesive story to a potential buyer. 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).

Admittedly the lines are blurring, with better UI design there is less need for the end user to head to the documentation for assistance but I’d argue that, conversely, as UI design improves and more people become aware of the basic principles of software applications (we all know cut and paste by now, right?) then the end users will start to stretch the applications in ways that hadn’t been considered and it is at this point that product documentation (information) becomes the key differentiator between products.

Of course it is possible to happily exist as a technical writer in an Agile world, but I think we need our voice to be louder.

So I guess my question is, who is willing to shout?

Note: I am aware of Agile Documentation, but I’ve yet to read it. It seems to be more focussed on a developer writing documentation though? I’ll post a review of the book soon.

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.

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.

Pre-Conference Dinner
The first day of a conference is always a little awkward, introducing yourself to complete strangers is always fraught with danger. So a ‘mingle’ activity is a nice idea, particularly as the TICAD conference makes some play of the networking opportunities, and the an informal dinner beforehand certainly made the following day a little easier. As it turns out I bumped into someone who worked at a sister company of my previous employers (it’s a whole complicated one company, then two companies, then one company thing), and we traded some names and stories.

Dinner was good, with many laughs and thought provoking conversation the kind of thing you get when you dine with a bunch of smart, friendly people. One topic which cropped up, and naturally I can’t recall why (did I mention the wine?) was Chess Boxing. Yes, that’s right, Chess Boxing. It was new to me as well.

The Conference itself is aimed at TechPubs managers and was celebrating its 10th year. Organised by ITR it has a focus on translation issues but is largely a TechComms focussed day. I’d heard of TICAD before but this was my first time both attending, and speaking at, the conference. The day was split into four sessions, the third comprising of two breakout sessions, the others more standard presentations. I took notes for all of the presentations but skipped the breakout sessions to go over my own presentation one more time.

Convergence in technical communications
The opening session was kicked off by Mark Wheeler of Adobe, and despite being fairly much a product pitch, it did outline Adobe’s thoughts concerning the convergence of various areas, with internal documentation, public documentation, Help systems, Knowledge Bases, training material and Demos all becoming more and more closely linked. All share similar traits, they all rely on high quality content for example, and organisations are beginning to realise the benefits of sharing information across these areas.

Part of the presentation did flummox me somewhat, and whilst it may have be a cool demo feature I do question the reality of usage. The idea presented was that by using embedded content within a document or help system, you could launch a video or “better still” initiate a text chat session or VOIP call to a support operative to help you with your current issue. Now, my belief is that, for that scenario, people want to get OUT of the help a.s.a.p. Why on earth would I want to sit through a video, or talk to someone and have to explain my issue, when all I want to do is get on with my work?

Naturally the focus was on the new Technical Communication Suite and overall it does look like it adds some value and will be of huge benefit to many technical communications teams. But then demos ALWAYS look good, don’t they…

Adapting structured documentation and DITA
When I saw this presentation listed in the agenda I marked it as one to attend. We are currently heading down the DITA path ourselves and Thomas promised to share some of the issues and pitfalls he and his team had come across. His presentation was excellent and hugely informative. A quietly spoken American, who was at our table for dinner, he covered everything I had hoped and more.

He covered the guidelines they had to put in place for help the writers cope with the move to structured authoring, including their 5 Glorious Principles (and yes I will be ‘borrowing’ this idea), namely that when writing topics:

1. Standalone chunking - create discrete chunks that contain only information about the topic/type.
2. Labelling - Titles are explicit, describe the topic (this also stops conceptual phrases like “this section contains” and so on).
3. Relevance - the content matches the topic.
4. Consistency - topics are written in the same way.
5. Reuse - topics are written once and can be used many times.

Working in a large organisation they found they had to hire a dedicated Documentation Product Manager, to coordinate and liase with Technical Publications, Training, Marketing and all other information creators. They also hired a dedicated architect to manage their DTD.

Outlining the drivers for their change, with localisation being the biggest (numerical) business reason, he talked through the planning stages, and admitted that they decided to stick to topic-level reuse rather than ‘conref’ level reuse (in theory you can reuse any single element, so a paragraph or list can be used in multiple topics) although that is something they are currently addressing. As a path to ease the pain of migration it is likely we will do the same, so it’s good to hear others taking the same route.

Technical English made simple
I wasn’t too sure what to expect from this presentation, but was pleasantly surprised. Admittedly as it was focussed more on maintenance style procedures, for hardware, then the suggestions didn’t always apply to a more software oriented team writing (or moving towards writing) in a task based style, there were still many valid points to take home.

Amongst the commonly held truisms, such as writing with an active rather than passive voice, Maria expanded on these topics with several examples, and the basic premise that most technical documentation is easier to read, less ambiguous, and easier to translate, if you simply consider each sentence and make sure you are assigning the task to the reader.

At present we don’t translate our docmentation but I am more than aware that someday, soon, we will be asked to do so. Some of the suggestions made by Maria will form part of new guidelines as we adapted our writing style to be more translation friendly.

In-country translations
Helen Eckersley, of iTR, gave a presentation which I didn’t think I’d take that much from. Focussing on getting the most from the people who review translated material it largely followed general practise for making the most of any kind of review, technical, linguistic or otherwise.

However, as it the way of things, it’s always good to get a reminder of such things, and similarly to Maria’s presentation I did gleen some information that, if put in place, should make translation of our documentation a whole lot easier.

Helen touched on linguistic assets, containing glossaries of approved terms (cross-language), translation memories, style rules for acronyms, product names and so on. All things we can consider now and start to build ourselves.

Using Wikis for Collaborative Authoring
Some Scottish bloke stood up and waffled on about Wikis, illicited the odd smile and largely left everyone bemused.

Vision of the future
The final speaker was Bernard Aschwanden, who I saw present at X-Pubs earlier this year. He is an animated, charismatic and passionate speaker and was given somewhat of a free reign to pull together his Vision of the Future.

He opened with a video, one which I think I’ve linked to before and which still bears repeat viewing.

Frankly the video is enough to get the synapses firing but building on that, Bernad took us back through the history of Publishing, from the first clay tablets, past the Guttenberg Bible all the way to Playboy. He tracked back through the advances in the past 100 years of technology, and then headed into the future.

Breaking things down into two sections, the first of which dealt with the coming 5-10 years, Bernard offered his take on where the traditional Publishing processes would take us. The basic premise is the same, regardless of the timescale, but the way in which information is handled and managed will change. For example, at present we spend a lot of time fudging with DTP packages to get information into a form that is legibile for our readers, in the next 5-10 years that will no longer be an issue (it’s already not an issue for some people publishing from a CMS system, where the template is applied and any layout errors automatically dealt with by the software.

He then tackled 25-100 years and whilst at first some of his premises seemed laughable - pulling the uploading of information from the movie The Matrix for example - he quickly reminded us of the change in technology in the last 100 years.

However, one thing remains true and becomes crucial in the future. All of the sources of knowledge really on people to check and validate the information on which it is built. Those people are the technical authors of today and in 10, 25 or 100 years from now, we will be in a far more powerful position than we are today. Bear that in mind the next time you ask for a raise!

All in all a fascinating presentation which I’m not doing justice. If you ever get the chance to see Bernard speak, do so. You can always tell when people are passionate about something, and he also has the knowledge to back that up.

My final thoughts
Sitting, as I am, on the train on the way home, it’s easy to pontificate about the things I’ve learned. Everyone returns to work after such an event, with a little extra enthusiasm and grand plans for change. However this time I do genuinely feel that there are things I will take from this conference that I WILL put into action, some of them require little extra work but can have huge benefits, others will need more contemplation but are equally valid.

The conference was very slick and well organised, credit to Tanya, Sally and all the other guys and gals from ITR, they certainly made it a very relaxing experience for me, very much appreciated as it was my first time as a speaker.

If you are a team lead, a manager, or have any sort of big picture thinking about Technical Communications then I highly recommend you head along to TICAD next year, you’ll find something of interest without doubt.

Hopefully I’ll see you there.

OK, I’m not really, I have a tendency to mumble and, being Scottish, I talk faster than most (I put this down to the speed at which Scottish women talk, you have to be fast to get a word in edgeways.. ). My mind wanders off topic quite easily and I tend to try off-the-cuff jokes. However I have given a presentation to a room full of strangers before but this time I may not be the only expert in the room…

These are all things I know I need to be aware of on Wednesday when I give my presentation on “Using Wikis for Collaborative Authoring” to the TICAD conference attendees.

However, I think my presentation is OK. It’s not going to “knock ‘em dead”, I don’t think, but I think I’ve pitched it right and hopefully I won’t trip myself up too often. I’m going to run through it twice more before Wednesday and, as yet, I’m not hugely nervous about it. I know the topic well enough, and I think I could even talk through it if the conference system fails so that should stand me in some good stead. Mind you, ask me that at 3pm on Wednesday and I’m sure you’ll get a different answer. Still, I know that is all part of the experience and I have to admit I am genuinely looking forward to it.

It is a little odd, as this is my first time as a conference speaker, to be on the ‘other side’ of a conference and I’m not really that sure what to expect. My slot is right after the ‘breakout’ sessions, with a coffee break preceding me and the rather awesome Bernard Aschwanden following me. Which reminds me that I must ask him about the theme of his session “A Vision of the Future” as I’m slightly wary of treading on his toes (he’s shorter than me though so it’s not too much of an issue…).

Still, at least I’m not right after lunch.

If you are coming along to the conference, then please say hello. I’ll be there from Tuesday evening at the pre-conference dinner, and I’ll most definitely be in the bar on Wednesday evening. Mine’s a Guinness.