Category: Work

What are you thinking when you review documentation?

We recently had a short discussion about how peer review, what we thought it was and how it should work. For us, having another member of the documentation team look over your work is useful for several reasons. Whilst we have distinct technical and editorial review stages, having another technical writer look over your work helps highlight things concerning structure, ordering and the killer of all killers, confusion.

Seth Godin nicely captured the reason why this is an important stage of information production:

If you’re building for digital, for a place where you can’t possibly be present to guide or to answer questions, I think it’s vital you have someone who can review your work … Not to make suggestions to make it better (what do they know?) but to share their confusions.

The thing is, it’s easy when you’ve been working on something for several weeks to get too close to the material and start making presumptions. These, inevitably, lead to confusion for the reader. It’s never an intentional thing, and everyone does it (and if they think they don’t, I’d suggest they may not be aware that they do!) but it’s something that we can easily catch.

The way we work, with each technical writer working on a distinct part of the product, it’s reasonable to assume that we can review a document without too much presumed knowledge. It’s not the same as handing the document to someone with no knowledge at all but we can usual spot those areas that may cause confusion.

Typically, these are the things that seem obvious when someone points them out, which a new customer will spot immediately because it leaves them perplexed. Unfortunately those are the moments when confidence in the content drops and, for many people, it only takes one or two instances of these for the documentation to be cast aside, never to be used again.

Catching points of confusion is a crucial part of any review process, it doesn’t really matter whether you have a specific process for it but it is something you should try and make sure you are addressing.

The next ISTC West of Scotland area group meeting in Glasgow will take place on Thursday 9th June 2011, from 7.30 pm onwards. Come along to talk about latest news and trends in communication, or just to meet other communication professionals.

The event is free and open to anyone interested in technical communication, such as technical authors, information architects, internal communication professionals, report writers, marketing writers, web content writers and graphic designers.

Venue: Waxy O’Connors pub, 44 West George Street, Glasgow, G2 1DH. Please make your way to McTurk’s Room on the middle level.

Please forward this message on to your colleagues or anyone else who may be interested. For more information, contact westscotland_areagroup@istc.org.uk.

A guest post by Noz Urbina, Mekon Senior Consultant and Congility 2011* Conference Chairperson

* Keep reading for discounted and even free entry opportunity.

The Hole in Holistic
There’s an industry buzz about Content Strategy. But, in it, there’s a tendency to define Content Strategy as near synonymous with internet marketing strategy, or worse, clever web copy writing.

There’s regularly an assumption that we’re talking about B2C mass-market writing where we’re trying to drive web conversions, ‘excite’ customers, and drive click-throughs.

Although web marketing projects need content strategy, I don’t think that adequately defines the discipline. All dentists are doctors, but not all doctors are dentists.

Content Strategy is in its adolescence, and the discipline is asking: Who are we? Why are we?

(more…)

I’ve written about social media before, and given presentations on Blogging and the wider use of social media as part of our professional toolbox. But that was mostly with a view to how these new technologies could be used to provide a better service to our customers.

So what does social media mean to me, as a professional?

Personally, away from Technical Communications, I’ve been involved and actively using various forms of social media for over a decade. It’s very much something I take for granted and expect to be able to communicate with people in a variety of ways. However, because I’ve been using this stuff for so long, I tend to fall prey to the curse of knowledge and forget that I’ve been through all of the decision points that many people are still approaching for the first time.

An example, which prompted this blog post, came via Twitter today when Marian Routledge asked “Social networking a valuable tool for keeping pace with developments in the world of tech comms or just another time filler?”.

My initial response was “‘another’? Social networking has been about in various forms for 10 years. If you aren’t using it, how else do you keep pace?” as, for me, use of social media is one of the most efficient ways of keeping up with all of the conversations and ideas that bloom and grow in these spaces. If I wasn’t on Twitter, if I didn’t read blogs, if I didn’t monitor RSS feeds from vendors and thought leaders, if I wasn’t on various mailing lists, then I’d have to rely on far more direct and expensive means of getting at that information.

Don’t get me wrong, social media is not a replacement for face-to-face communication, never will be, and so conferences and meetings are still required, but I’d argue that those activities are enhanced through attendee use of social media.

One thing which many people have suggested is that, as accessing information online is so easy, we in danger of filling our time with all this extra information. I’d suggest not, but I know there is a chance that you could, very quickly, become overwhelmed by the amount of data pouring your way.

However, i tend to think of all the RSS feeds I monitor, the people I follow on Twitter, and the numerous blog discussions that I participate in, as one big stream of information. I can dip in and out, safe in the knowledge that if something important passes by unseen, it’ll no doubt come floating past again when someone else mentions it.

Does that stream of information make me better at my job? I think it does. In a way it’s like an extended conference, that buzz, the sharing of common ideas, the conversations between sessions. Being involved in any aspect of social media is exactly that, an extended conversation. There are some key words in that last sentence, and this, if anything, is the take home advice from this blog post.

“Being involved” in social media is a lot different from letting it flow into your inbox and swamping you. If you are involved you will know what conversations you can ignore, and what trends/people you should be following. To be involved you need to remember that social media is, and always has been, a conversation. It’s a two way thing, and the more you contribute to that conversation, the more you’ll get out of it. Comment on blogs, reply to updates on Twitter, publish your own ideas and respond to those who show an interest and you’ll soon find yourself part of the community. It doesn’t have to take a lot of effort, at most it may take 15 minutes a day if you are diligent, but the more you get involved, the faster you’ll be able to process the information coming your way.

At this point I’ll stop waffling and point you towards the latest addition to the growing set of social media resources for Technical Communication professionals. It’s called Technical Writing World and is already shaping up to become a useful place to discuss ideas, share problems and get solutions to the everyday issues we all face.

If you are a technical communications professional, and have still to get involved with social media, then Technical Writing World is a great place to start. It’s small enough to be easily managed, and interactive enough that you’ll be able to converse with technical communicators from all over the globe.

Go on, sign up, say hi and get involved. I can’t wait to hear what you have to say.

I’m always wary of buzzwords and industry fads, and will always take, primarily, a business focused view on any new theory (or strategy) that I hear about until I fully understand its real life application. Such is the case with Content Strategy.

It’s something I’ve talked about on here before (under the guise of Information Strategy) but whilst I’ve a good idea of how it could benefit our company, I’ve struggled to get buy-in. Whilst Content Strategy discussions go well, everyone thinks that a coherent and consistent set of content is a good thing, where we seem to struggle is getting commitment to getting the actual work done to bring things into line. The high level Content Audit I completed about 18 months ago is about as far as we got.

So, rather than try and get everyone on-board from the outset we are now starting from the bottom up by providing a technical product information service to our sales team. Essentially, our team will be providing source content that can be used by our PreSales team to inform potential customers what our product can do. It’s an important part of our sales cycle, and will mean that we will have a consistent set of information, used across different areas of the company, all sourced and developed with a common view (and reuse) in mind.

The route we are taking towards a company wide content strategy may take us a while (my gutfeel is that, once the ball is rolling and word gets out, other areas of the company will soon come on board) but ultimately we will end up in the same place. The advantages are that we can make decisions on the way, replan a lot more easily (we don’t need to get it as ‘almost’ right as we would if we were tackling a larger amount of work) and crucially we don’t need any ‘stop the world’ moments.

I work in a fast paced company, we are light on paperwork, and whilst we apply good rigour and quality to what we do, we only do whatever we need, and are quick to change or drop processes if they bring no value. It’s a great place to work, but keeping up with the pace of change in our product is a constant challenge to the technical writing team, so this approach to tackling the introduction of a content strategy stands a very good chance of succeeding.

Naturally this approach will present some challenges, we will probably need to schedule some form of review of the work as it progresses to make sure it’s not becoming too focused on it’s initial use, and I’ve no doubt that we may have to rework some of the content later on when we have a better understanding of the big picture, but I think it will work.

And hey, life’s nothing without a challenge!

Part way through April and the discussions and planning over the past few months look like they are, slowly, starting to come together.

The plans are ambitious, not only are we restructuring our information offering to make things easier to find, we are also attempting to change the way we document our product. Moving us away from a set of information that covers “here is what our development kit can do”, to content that says “this is what our product does and how you can extend or modify it”. In one way it’s a subtle shift, but the ramifications are still unfolding.

One area in particular will be interesting, namely that we will be asking “why that way?” a lot more than we have in the past. In the past, as we were light on content in several areas, we steered away from such questions where we could, but now we need to tackle them head on which, invariably, will mean we will start to drive some interesting conversations about how our product SHOULD be used.

None of this is, as ever, rocket science, but there is a level of change management that we need to consider.

In the end we should end up with, in essence, an information matrix.

Down the left side will be headings corresponding to the types of content we have (or need to write), and across the top will be a list of the areas of the product we document. I say “will be” because we are still trying to fully understand what those areas are, and to make sure that the terminology we use will be understand and used consistently across the company. Once that matrix is in place, we can audit what we have and see where the gaps are.

Thankfully, once we understand the new structure, the act of restructuring the information will be easy. The joys of single source, topic based authoring!

I won’t, however, mention the third level of complexity we are trying to tackle as I’m not quite sure I’ve got a handle on it yet. Suffice to say that we need to make sure the new information structure we decide on within the product documentation, also needs to fit into a wider piece that is being introduced to our developer community website (same basic idea though, creating landing pages on ‘topics’ or ‘product areas’ to direct users to product documentation, elearning material or support notes).

It’s a bit like doing a big jigsaw and at the moment I’ve only just managed to finish the outline.