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.

I’ve mentioned DITA a few times on this blog, and my DITA is not the answer post is still attracting attention. As I’ve said, I think the DITA standard is an excellent one for software documentation and the DITA movement is slowly catching up to the hype. I’ve never given up on DITA and had always planned to use it as the basis for the next stage of our content development, and as it happens the switch to a full DITA/CMS based solution may be closer than I had anticipated.

We have been considering how best to publish up to date information in keeping with patches and minor releases, and if we can tidy up and publish useful information from our internal Wikis and support system. The nature of the product we work with means there are a lot of different usage patterns, not all of which we would document as they fall outwith typical (common) usage.

So, how to publish formal product documentation, in-line with three versions of the product, in PDF for ‘printed’ manuals, JavaHelp to be added to our product, and HTML to be published to a live website alongside other technical content (ideally maintained in the same system as the product documentation). Storing the content as XML chunks also allows us to further re-use the content programmatically (which can be tied into our product in a smarter, dynamic, fashion).

The obvious answer is single source using DITA to structure the content, storing the content as XML to give us the greatest potential avenues for re-use. Nothing particularly startling there I know, but it’s a switch from the direction we had been considering. So I’ve been catching up on what’s new in DITA-land and have to admit I’m a little disappointed.

We already have FrameMaker and Webworks in-house, although both are a couple of versions old, and thinking we might keep using those applications I’ve been hunting about to see if I can find a solution that offers a coherent, end-to-end, story. There are several CMS solutions which require an editor, editing solutions which require a CMS, and a few products that straddle both CMS and editing but then require publishing engines.

I understand that it would take a collaboration between vendors to be able to offer a simple, seamless solution

In addition to that there does seem to be a tendency for any DITA focused solution to remain the remit of the overly technical. Don’t get me wrong, I’m quite happy delving into XML code, hacking elements, or running command line scripts to get things done. But surely I shouldn’t have to resort such things? Now, I’m sure there are many vendors who will tell me that I don’t need to worry, but I’ve seen several demos and all of them miss a part of the FULL story.

Come on then vendors, stick your necks out. If you are a CMS provider, then recommend an editor. If you sell editing software then talk nice to a CMS vendor and start promoting each other (yeah Adobe, I’m looking at you!).

And yes, I’ll happily admit that maybe I’m just not looking closely enough. If only there was some sort of technical community website that I could join, perhaps with a group or two on DITA? That’d be great.

Ohhh wait. There is! (not the most subtle plug in the world, was it? I think the new Content Wrangler communities could be a big hit, do check them out).

Have a got the wrong end of the stick, are there really gaps in the market in this area at present or is it just my imagination? I guess I’ll be running a fair few evaluations over the coming few weeks and, of course, I’ll post my thoughts and findings here.

Recently I’ve been toying with some software tools to try and focus my writing a little better, stumbling across an application called Q10. A full-screen text editor which is, according to the website, “a simple but powerful text editor designed and built with writers in mind.”

Whenever I start a new piece of work I tend to write up notes in text files first, before moving them into FrameMaker for formatting and publishing. This was largely borne from limitations in Structured FrameMaker, and sits well with our usage of an internal Wiki for content collaboration. Q10 helps with this approach by doing one thing very well.

Like most well-designed products, the features are usable out of the box, but there is enough scope for tweaking things to get a system that suits you. The full-screen aspect of Q10 is the most important, blacking out the rest of the screen and leaving you with a blank slate on which to focus your thoughts. There is no menubar, with options only available through keyboard shortcuts, including one to turn off the typewriter noises which I’ve left on as they are somewhat soothing… oddly.

You can set the file encoding, a target number of words (handy if you are writing an article), change the font and colour settings, and it supports quick text allowing you to replace given character combinations with whatever you specify (I use this for product names, although you have to search and replace on the underlying text file if the name changes).

At first I was only really using Q10 for writing blog posts and articles, but I’ve started to extend it into my set of ‘work’ tools and it’s proving very useful. Sure it gets some odd looks as people glance at your screen but I certainly seem to be more capable of focusing on my writing these days.

I’ve tried a few other full-screen text editors (for Mac and Windows) but as the bulk of my writing time is spent on Windows machines, Q10 is proving very useful. Best of all it’s free!

The tool is not important. The tool is not important. The tool is not important.

I have been repeating this mantra in my head for the past week or so, over and over, like a broken record. I’m in the middle of pulling together the requirements and scope for a new technical community website for our users, which will become the key focus of our technical information. The more traditional product documentation set will be maintained as we move forward, so there is some thought to be given towards how we manage the information as well as how it is published, or rather where.

I must stop considering the how. The tool is not important.

At present I have a list of requirements, all of which I’m thinking through from the point of view of how the process will work as far as creating and maintaining the information. Who will be access the source, who will be viewing the published information, who can edit what, how will the information be used by the audience? All the while there is a part of my brain dragging me towards HOW this will work. What tool will be able to handle our requirements?

The tool is not important.

I enjoy a challenge, and this is most certainly a new venture for me, but the basic foundations of this idea are rooted in things I know well, single sourcing content, developing online communities (I run a website for Scottish Bloggers (currently dead after our hosting service disappeared)). As such I’m confident I can get this off the ground, but even so I’m being careful to properly gather requirements, and fully understand the impact of changing our publishing model. Note I said “model”.

The tool is not important.

So with a list of requirements, and a full understanding of the processes that will be involved both to maintain the main documentation set and the development of other supporting information (culled from internal Wikis, mailing lists and anywhere else we stumble across something useful) one change is the way in which we plan, design and write product documentation.

As I’ve said, this is all about the processes that support the way we work. I’m being quite deliberate in how I pull together the requirements, focussing discussions on the audience, the expectations, the information and processes, with no mention of the technology which will need to support the new website.

The tool is not important.

Last year’s X-Pubs conference drilled this message home, and it’s good to be able to draw on the information and knowledge gained there. Get your requirements sorted out and agreed, understand the impact of changing the way people access information, and the impact of changing how people work, figure out how best to handle the reaction to change and agree the expectations and limitations of your system. Decide which models you will follow, how the processes will hang together and outline the various roles that will be required, and make sure they understand what is required of them.

Then and only then should you consider what tools you require and make sure they are serving you.

As I mentioned previously, the opening presentation at TICAD was by Adobe and featured their vision of the future of Technical Communications and information development. Apparently that future includes video.

Video has been available to many for a few years now, yet it is never really the main focus of a documentation team. Tom has questioned this as well:

“For too long I’ve minimized the importance of the audiovisual. Captivate — the industry standard tool for creating screen demos — is actually a relatively simple application. Mastering it and integrating audiovisual into user help will take it to the next level.”

This echoes what Adobe suggest, no big surprise there, but I have to admit that I don’t fully agree.

As a quick learning tool, I’m sure videos (screen demos) are useful, but I wouldn’t really know as I’ve never used one as a primary source for learning about a product and I’m not sure I know anyone who has. Of course that’s not to say they don’t have value and with some research into the intended audience I’m sure it can be proven that they have a valid place in the product documentation set.

However my initial thoughts on the matter are hard to shake.

It may be one of the unwritten rules of documentation, the rules that few people question and may well be inaccurately applied, but I’ve always operated under the assumption that people only use the documentation when they are stuck.

Of course this is a broad sweeping statement but I believe that it is true for the majority of software users. So, if that is the case, what is their mindset when they finally give in (having asked a co-worker and searched Google to no avail) and fire up the online help or open the user guide? Typically they will be annoyed and want an answer or fix pretty damn sharpish.

Why, in that case, would they even consider sitting through a 2 minute video that explains how to use the functionality with which they are currently battling?

To be fair, Tom isn’t suggesting this approach but I think it’s wise to counsel against this trend lest it be used too heavily. A few short demos of how to complete core tasks, accompanied by a comprehensive help system or user guide is the best balance.

My fear is that the “cool” effect will override sensibilities and we’ll be plagued by popup videos and worse in the future.

The written word certainly isn’t the only way to effectively communicate information, and as technology progresses we will all need to carefully match the available delivery mechanisms with the information we need to deliver. The key word here is “carefully”.

I’d love to hear from anyone who is already doing something like this, I’ve not used Captivate, nor offered any form of video as part of a documentation set before as they didn’t match the audience profile but I’d be interested in hearing how successful they were.

A big hello to anyone visiting from the TICAD conference. I’m writing this post in advance of the conference itself (the joys of scheduled publishing), so hopefully my presentation went well and you found it useful. I hope the page of links I mentioned is of some use to you and anyone else who pondering whether or not a Wiki lies in the future of their organisation (yes, it does!).

The very act of pulling the presentation together has been both fun and educational for me, it has helped me fully understand some things I took for granted and hopefully that is reflected in my words. My thoughts on the experience, and the rest of the conference sessions, will be posted here soon.

If you are visiting from the TICAD conference, please leave a comment, any and all thoughts, feedback and criticisms are encouraged.

Having recently upgraded my MacBook to run the latest version of OSX, I’ve been using the built-in Help to figure out how to configure things to the way I like them. It’s an excellent example of well designed and integrated help. Of particular note is the effect shown in the screenshot below.

An excellent example of integrating user assistance with an in-built online help system. Don’t you think?

Typing in your question to the text box, top-right of the window, dims the contents and ’spotlights’ the items which possibly match what you are looking for. Smart, huh. There are many more examples of this kind of thing but this one caught my eye.