As part of the product, testing documentation seems like an obvious thing to do, but what does it really mean? I’ve fielded the question in a few different places now and it’s always interesting to delve deeper and understand the rationale behind the request.

“We should test the documentation”, seems like a harmless enough statement and I’ve heard it uttered in more than one place yet I’ve never worked in a company that actually tested the documentation.

Some clarification is usually required, of course, as there are many ways that you could test the documentation, for example:

• For online help, test that any hooks from the application to the documentation work properly
• Check that cross-references are corrected and, if hyperlinked, work properly
• Test the content matches exactly what is on-screen
• Test the flow of information is correct and makes sense from a users point of view

Now, we do test that our online help works correctly, that the correct page is launched from the application and that a sampling of internal links work correctly.

However, the last two items in the list can be a bit of a thornier issue. Testing the content is a much bigger job than most realise, presuming it is being done correctly and it also raises the fun issue of is this a bug in the documentation, or in the application.

Every time I’ve had this question asked I’ve said yes we should test the documentation, but what I really mean is that we should use the documentation to test the application. One method I’ve thought about is to have one person would read out the instructions, with another piloting the application. Just an idea but it would flag up some issues in both areas, I think.

Of course such resource heavy requirements rarely see the light of day and the simple fact is that we don’t test the content of our documentation. Yes we get it reviewed but they are separate (if closely related) things.

So, in an effort to close the gap between reviewing the documentation and testing the documentation, it is probably worthwhile running a short workshop for your development team, a 10 minute session that shows how best to review documentation. I’m planning such a workshop at the moment, so more on that, soon.

Anyone working in the software industry will know the term “usability” and have a reasonable idea of what it entails. As a technical writer, a user advocate within the development team, there is typically an overlap between how we think, and how usability specialists think.

For starters, anyone who is delivering information should know who their audience is and why they require the information. With a good understanding of your audience, you will know what information they require because you will understand how they use your product.

It seems obvious yet it’s something that many people struggle with, and I wonder if it is partly because, rightly, usability is a distinct field which has many experts and practitioners.

However, many software companies do not have resource dedicated to usability as, and I don’t get to say this often, it’s often seen as less of a priority than technical writing.

Why does any of this matter to you as a technical writer? Because it’s another string to your bow, another item to add to your CV, and something else that will convince your boss that it’s worthwhile keeping you in the team.

And hey, it’s interesting stuff, a little task analysis of the requirements, some creative thinking, and an even better understanding of the product and then, if you are really lucky, you get to talk directly to users of your product.

I’m part of the ad-hoc usability team in my company, and whilst it can be challenging it is part of my job I hugely enjoy and which makes me a better technical writer, and that’s never a bad thing.

When do you publish (release) documentation? Inline with the latest version of your product I’d expect as that’s the traditional model and, and believe me I hate to be the one to break this to you, that’s no longer acceptable.

Please don’t shoot the messenger, it’s not my fault, if you are going to blame anyone, blame Google. Or perhaps Tim Berners-Lee.

Now, to say that the traditional “publish alongwith product versions” model is broken is a bit of a sweeping statement and of course it still has a place, will be and should be followed but have you ever taken a close look at the information you provide? Is it ALL based only on new features?

Maybe it’s just me (hey, it frequently is) but a lot of the information produced is sensitive to version not time, and as such can be published as and when it becomes available providing it has appropriate meta tags. Why do we wait until a product release is due to publish non-version specific information?

Of course there are a multitude of reasons why this may not be valid for you, but having looked long and hard at the information my team produce, I’m increasingly finding that a lot of it can be published instantly and, given that most computer/internet literate people are used to demanding information immediately (thanks Google!) then this at least goes partway to meeting that need. We are lucky in that we have control over where and how our information is published, and we’re slowly moving away from a document and release centric system to a more dynamic and immediate method.

After all, if our customers want information, and our job is to provide them with information, why are we waiting?

Recently Scott Abel posted a heartfelt plea to get people all psyched up about how to better promote DITA to the rest of the world. He backs the idea of the DITA Adoption Technical Committee, stating that:

“we need excellent communicators with the gumption, know-how, and network to get the word out about the many ways DITA impacts the world and those who live in it.”

I’m a fan of DITA and as I read his post I could feel myself getting quite excited, he makes some excellent points about finding real world examples of the benefit DITA can bring but something just doesn’t quite fit. It’s taken me a while to get my head around this but, isn’t a standard supposed to be a technical implementation detail, not the main focus of life changing events? Ahhh but wait, Scott agrees:

“DITA cannot be the focus of DITA adoption and publicity efforts.”

OK, so we can’t focus on DITA itself and, as Scott rightly points out, the software vendors will soon turn discussions away from DITA and towards their own feature set, so we can’t look there for an example either. In fact it’s not until the latter half of the post that Scott really hits on what he would like us to do, and in my opinion the following sentence is the key to his entire argument:

“Let’s strip away all the noise that prevents normal humans from understanding what we technology addicts find so wonderful about DITA, XML, content reuse, content management, dynamic content, personalization, and so on. … The focus has to be on the human impact. How does DITA help make the world a better place? How does it make it possible for humans to interact with one another? How will it help everyday humans in their everyday lives? How can it help governments better serve their citizens?”

Big questions.

Whilst Scott is aiming at a top-down view of the world, there are lessons there for those of us who are trying to push these things upwards. Selling DITA as the fundamental part of a single source solution now seems a little odd, particularly when most business cases are focussed on ROI and the whys and wherefores surrounding the choice of tooling, so if you can detach the tool from the business case, and focus thinking on the benefits of DITA (rendering the tooling generic rather than specialised) you can start to really crack the story behind how adopting DITA as a content standard will benefit the customers of your company, THEN you have a much more powerful argument.

So, if anyone has any answers to those big questions, do let me know…

A quick welcome to anyone visiting from the ISTC Communicator magazine. I feel a little spoiled getting two mentions in subsequent pages (10 & 12 if you are wondering) but I’m not really complaining.

Over the past year or so I’ve definitely got the feeling that the ISTC is changing, and it certainly feels like a more modern and dynamic organisation than it has seemed to be in the past. Perhaps that’s natural, but it’s amazing how little things like a redesign magazine and newsletter, and hopefully a new design for the website, can refocus the energies of those involved.

Anyway, thanks for dropping by, there are plenty of links and opinions to be found in the archives (scroll down a bit, they are on the right), and here are a few of the more popular posts:

• Everything is Connected
• DITA is not the answer
• Technical Writing evolved

Or perhaps you just want to download the RSS feeds.

This post has been bubbling for the past year or so, ever since I started this blog. It’s a bit of a ramble but if I don’t publish it now I’ll just keep adding to it and it’s long enough as it is!

I question everything. It’s part of the way my mind works, and is something I’ve embraced and believe it makes me better at my job as a technical communicator. That attitude has also helped me realise that there is a common thread that can be found across several different areas of our industry, which I (and others) are slowly pulling together. Convergence is the word that springs to mind, and as businesses clamber onto the social networking bandwagon, now is an excellent time to grab the reigns and take control.

Let’s step back a little.

Late last year, on two separate mailing lists, I followed discussions about what the myriad of people who share my profession have as job titles. I prompted one discussion on the ISTC mailing list, and chipped in some thoughts on the TechWR mailing list before dropping out later on when the noise ratio, as ever, got too high.

I wonder how much useful information I miss when I do that? Ahhh something else to ponder. But not today.

Anyway, discussions around how we as a profession should be referring to ourselves, envitably leads to discussions and thoughts about what we do, where our skills lie, and the benefits we can bring to an organisation. Something I’ve toyed with before, but which is wrapped up in many layers of ifs, buts and other such caveats.

Following on from that, I read an article by Virginia Lynch in the CIDM newsletter (and if you aren’t subscribed to their newsletter, you should be) entitled Information Developers - The New Role of Technical Writers in a Flat World which encapsulates a lot of my current thinking on how to take my current team forward, making sure we are matching company strategy whilst allowing the team members to retain a focus on maintaining and developing their core skills. The article title rather neatly alludes to Thomas Friedman’s book The World Is Flat: The Globalized World in the Twenty-first Century which is certainly worth a read.

Virginia mentions that JoAnn Hackos recently referred to these core skills as “Basic Hygiene”, citing the fact that, regardless of how the collation and production, distribution and usage of information may change, as we explore the burgeoning arena of new tools available to us under the banner of “social web applications” our core skills remain. Typically they tend to drop off as we are pushed to create more, faster, with a rise in quantity favoured over a maintenance of quality.

style, grammar, punctuation, spelling, and even clarity seem to have been sacrificed for quantity —JoAnn points out that knowledge of basic writing skills is still critical to our success as writers. Basic Hygiene also comprises an understanding and appreciation of editing, the information development life cycle, fundamental web and computer skills, and of course attention to detail.

However it is important to note the nod towards quantity being a business leader, and those of us tasked with managing a team need to consider how we achieve that business aim, without impacting our integrity as Technical Writ… umm… Information Developers?

So, how do we produce more whilst maintaining quality?

Wait! What’s that coming over the hill? Ahhh yes, the shining white knight of single source, armour gleaming, his trusty DITA (or DocBook) in hand, ready to do battle against the ills of productivity measurements and over-zealous QA departments. What else were you expecting? Ohh more resource? No, not these days when everyone is a “content creator”, not these days when we should be embracing and encouraging our audience to help plug the gaps in our information dykes (I really must stop mixing my metaphors).

Topic-based writing certainly seems to tick the required boxes and every business case and ROI I’ve read (and I’ve written a couple myself) points us towards the promises found over the horizon and the “he’ll be here real soon, honest” arrival of the aforementioned white knight. The trouble is that, whilst it is easy to agree with the theory, I’m not all that sure the white knight is all he seems. Certainly as we climb the hill towards him, auditing our content, deciding on chunking levels, agreeing metadata requirements, we begin to see that that armour seems a little thin and dented in areas, and I’m not entirely sure the knight is filling that armour as much as he should. Aren’t they supposed to be big strapping warriors? He looks a little weedy to me…

Topic driven content written with a minimalist slant, deferring here to the instructions of Strunk and White* rather than Roy Carroll, are where we seem to be (need to be?) heading and that’s fine and good from where I’m sitting.

* A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid detail and treat his subject only in outline, but that every word tell.

On the flip side, there is a definite growth in awareness around the use of Web 2.0 technologies and systems, building online communities, integrating Wikis, blogs, RSS feeds into the information flow either as part of end user deliverables or as methods for encouraging information creation by everyone involved with the product, internal or external.

A large part of our job concerns the collation and filtering of information so as far as I’m concerned anything we can do to make the creation of source information easier has to be welcomed. Extending these mechanisms beyond internal usage means it should be easier to provide information to the people who really need it, with the added bonus of a greater level of trust in that information. Don’t believe me? Which type of information do you put most weight on, the information passed to you by a trusted colleague who you know uses the product heavily, or the product documentation? (and bear in mind that we technical writers pre-disposed to favour the work of our peers). That in itself is another issue which may be alleviated by embracing social content creation, pulling on the goodwill generated by openly inviting contribution and collaboration, whilst giving technical writers a chance to show their worth in full public view.

So where is all this heading? I’m not sure if anyone is too sure but there do seem to be some trends appearing. The use of Wikis to host documentation, the creation of community websites with few restrictions, and more. There are plenty of tools, and with a little work you can get them talking to each other. Technology is not the limiting factor anymore, attitudes are now the only things stopping us trying these wonderous new things. It’s a big step for some companies, and some people, to free their information, to pass their hard earned knowledge about willy-nilly without a clue as to how it will be used.

Once you’ve gotten past the limitations, the real effort, once you have your community or collaboration up and running, is the surrounding processes. Do you want to pump content into the website regularly? (yes). Do you want to allow anyone and everyone to contribute to that same store of information? (yes). Do you want to allow others to quietly correct your mistakes? (yes). Do you want to give the people who need it, access to information about your product, regardless where it originates, trusting them to use their judgement? (yes).

The final pieces of the jigsaw are the finer details of implementation. Presuming we want to reuse information as often as possible where do you store information and how do you allow access to it? Who should be involved in verifying new information? Where/how is the level of trust established?

Pulling together the threads of this emerging role is tricky, with so much overlap into multiple areas and so much to consider there is a danger of not seeing the wood for the trees. This post is an attempt to step back and make a little more sense of what I can see, what I know, and the changes starting to drag our profession in interesting new directions. I fear I may have muddied the waters, but hopefully they’ll settle and things will start to make sense.

Regardless of whether I’m right or wrong, one thing is for sure, these are exciting times and we have a great opportunity to finally leverage technical communications into the spotlight. The value of information is finally being properly realised, and we are ideally placed to help any organisation make the most of what information they have and help them understand and create the information they really need.

Re-reading the article I submitted to the ISTC Communicator magazine, I realise that my average day isn’t:

• particularly average at all
• a true representation of everything I’m involved with

I lead a team of writers so my typical day may not apply to everyone, and I also have a tendency to stick my nose in and get involved in other areas if I feel I can be of help. Simply put, if I hear someone talking about “information” my radar pings and I see if I can be of any benefit.

Other non-typical items include collation of Product Release Notes, my team proof-read Marketing brochures and website collateral, we try and monitor consistency in the UI of our customer facing product, and I’m currently in the process of creating (and managing) and developer community website. As an “unbiased” member of the development group I also recently facilitated our retrospectives.

One of the reasons I love this profession is that you can (and should?) be involved in many different areas. We have a unique view of the product and I guess my day is sculpted by that, although it is helped that we are a small(ish) company and have a small group of people thinking about the “product” as a whole.

I’m lucky that our company doesn’t have a traditional structure, with everyone encouraged to talk to everyone else regardless of role or level. It’s a little like a zoo sometimes, with a lot of noise and activity, but apparently that’s a good thing. It does mean I am involved in discussions that can be hard to be a part of otherwise, chatting to the Product Manager, Product Marketing and Sales, all of whom are saying the same thing, which in itself proves that things are working and that technical writers are a valid part of that discussion.

I’m curious to hear if others have the same opportunity; What other areas, outside of technical writing, are you involved in? And why?