Conference season is underway, with DocTrain and AODC recently finishing. As such there is a lot of great and interesting blog posts out there, some are catchup style so if, like me, you didn’t attend you can still get some nuggets of information from them. But the type I prefer are the ones which collate the various ideas and pull them together.

So, with that in mind, if you only read one of the posts linked below, make it the first one.

DocTrain Conference thoughts
Tom chats to Noz Urbina from Mekon and starts to pull together some of the varied threads I’ve covered here into a vision of the future which, in my opinion, makes sense. It’s great to see this kind of thing being discussed and it’s the step beyond where I’d gotten with my thinking. Well worth a read.

Some thoughts on writing better error messages
Real-world tales of woe shed some light.

This lack of coordination between error reporting and error origin often leads to incorrect human reasoning about root causes. One simple help to sysadmins (and other users) would be to report errors in context.

Separating content, structure, format and behaviour
One from a session of AODC which helps properly define how and why we should be separating out the various components of information production.

What we’re aiming for:
* Maintainability — you can change one of the above four components without breaking the others.
* Re-usability — you can re-use the same bit of JavaScript, for example, in other documents.
* Separation of skill sets — different people can work on the component they know best and enjoy most.
* Simplified updating of content — content is likely to be the component you update most often.

Designing for the Social Web: The Usage Lifecycle
Pertinent to anyone working with an application that has any form of social web (web 2.0, community interaction, pick a term) features, or for those of us trying to build an online community around their product

The lifecycle is particularly relevant to web-based software because the product is inextricable from the service. The product is the service. If a person has a question about what your software does, for example, you can literally build that answer into the software itself.

Wiki on a Stick
And finally, a downloadable, zero install, personal Wiki. May be useful if you want an example of how Wikis work. Extra handy for maintaining your own To Do lists or as a way to centralise your notes (or both).

That’s all for now.

I took a few days holiday last week (if you get the chance, go visit Budapest, it’s lovely) so here’s a little bit of catchup from the RSS feeds I monitor. You can download the list over on the right there.

How Corporate RSS Supports Collaboration and Innovation
Dennis McDonald pulls together some good arguments around introducing Web 2.0 ideas to your company, noting that a lot of business cases rely on raw numbers and that, in the case of social networking tools, there is:

… a disadvantage of taking a “beancounter” approach to implementing social media within an organization. While you might be able to quantify the time, effort, and technology associated with impacted processes, you can’t necessarily predict when and where the benefits (such as innovations or new ides) will occur.

Bye Bye GoLive!
Adobe finally realise what most web developers already knew, GoLive can’t compete with DreamWeaver (also now owned by Adobe). However, it’s not all bad news if you are a GoLive user:

the company will continue to support GoLive users with online tutorials and migration assistance created by usage experts. The company has also collaborated with online training service Lynda.com to provide tutorials for GoLive users.

And one more thing
The Hoefler & Frere-Jones blog continues to provide some fascinating information for typographists (?) and writers alike. This time they take a look at the many forms of the ampersand.

As for the word “ampersand,” folk etymologies abound. The likeliest account, offered by the OED, is explained by early alphabet primers in which the symbol was listed after X, Y, Z as “&: per se, and.” Meaning “&: in itself, ‘and’”, and inevitably pronounced as “and per se and”, it’s a quick corruption to “ampersand,” and the rest is history.

The Dawning of the Age of Content - and why Content Convergence Matters to You
For anyone watching the way information is now created, collated and distributed on the world wide web, this article will ring true. We ARE all watching what is going on, aren’t we?

We’re all content producers. And we’re all about to live through interesting times with the dawning of The Age of Content. Industry is discovering content as a commodity, as inventory with value, and the rules are changing fast.

The new rules are not just for high-profit content like movies and music. What was once seen as the lowliest form of commercial content within an enterprise - technical manuals, support documentation, and other business content - is starting to take its place alongside other valued corporate assets.

The 10, 20, 30 Powerpoint rule
An oldie but a goodie, it’s often quoted but it’s worth re-reading (especially as I’ve just pulled together a presentation that has.. eh… 23 slides.. ). It’s not always applicable of course but well worth keeping in mind.

It’s quite simple: a PowerPoint presentation should have ten slides, last no more than twenty minutes, and contain no font smaller than thirty points.

Summer of Doc, anyone?
Janet has a good idea for getting student technical writers (and hey why limit it?) a little bit of experience.

Now in its fourth year, Google Summer of Code supports students in writing code for participating open-source projects, which provide mentors to help guide the students’ work. Thanks to Google’s sponsorship, the students receive a stipend (making this a summer job), and mentors receive a nominal compensation for their time.
…
If you substitute code/documentation, developers/tech writers, Computer Science/Technical Communication, I think it’s fairly obvious that the same benefits could apply to Tech Comm students writing documentation for open source projects.

And finally a nice quote from the late great Douglas Adams:

” I love deadlines. I like the whooshing sound they make as they fly by. “

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

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

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

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

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

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

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

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

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

Prompted by an excellent article - Subversion for writers - I thought it might be useful to offer a Windows view. Like most software groups, our development team use a version control system to manage multiple versions of the product; we have customers using many previous versions and all are maintained in the same system so we can patch fixes back through multiple versions.

Our team of writers use the same system, although as we are using FrameMaker we lose some of the nicer features but the core reasons for using a version control system remain - files are locked by whoever is working on them, and we have a full version history of changes made, including when, who and why.

|Read the Rest of the Entry…

Back from a short break in Hungary (Budapest is a glorious city, if you ever get the chance you must visit it) I find myself wondering what to do next. I was looking forward to the trip and have been building towards it for several weeks now. I had planned my work around it, knowing what I needed to do before I left and with a rough idea of what I need to do when I go back.

It’s a little different here on this blog though.

I’ve just re-read my previous post (the big long one below) and it strikes me that while it may be interesting to some it suggests I may be at a point in my career where I need to practice a little more of what I preach.

In other words, I need to start to try to do all these things I’ve mentioned, rather than theorise and prevaricate over the nuances. But then that’s a bad habit of mine.

Sometimes you just need to put up or shut up.

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 spent most of the weekend laying, re-laying, cutting and swearing at laminate flooring. I read the provided instructions, measured twice (hell, four or five times in most cases) but still it proved problematic. I re-read the instructions, googled a little and then, after some experimentation finally figured out what the problem was… me.

Well not just me, but my interpretation of the instructions which were a little vague in one key area. Namely, where to start. This is crucial as, most laminate flooring needs to be laid the correct way to make it possible to snap all the pieces into place. It’s a one-directional jigsaw puzzle, if you will.

The details here aren’t important, but what it taught me (for the umpteenth time I guess) is that documentation needs to be complete, unambiguous and for hardware related matters at least, a picture tells a thousand stories.

I keep going back to the assumed knowledge angle, and it rings true for this example. One of the forums I found during a frantic Googling session yielded a comment along the lines of: “The professionals know this but it’s not something you’ll find in the instructions”.

I have been guilty of this in the past. Presumption is the silent virus that can kill an otherwise excellent piece of documentation stone dead. All it takes is one presumption to render an entire document AND THE PRODUCT IT IS SUPPORTING, next to useless (or at the very least “problematic”). Introducing that kind of negative thinking at an early stage of the product lifecycle makes it very hard to undo.

Although that, itself, is a presumption. I’m presuming that most people only read the documentation when they are still novice users. So maybe that is another presumption that I need to work on removing.