(OK, mainly aiming at West of Scotland)

Following a recent discussion about ISTC local area groups, a few of us based in the West of Scotland have decided to try to set up a local group.

Our first meeting will be on Thursday 15th January 2009. If you work in the area (or further away), please come along to meet other writers and talk about technical writing.

We’ll meet at 7 p.m. in the offices of Sumerian in Glasgow city centre, at 19 Blythswood Square, Glasgow G2 4BG. Tea & coffee provided.

If you plan to come along, please email me so we can get a rough idea of how many writers might be attending:

gordon [DOT] mclean AT gmail [DOT ] com

(if you can figure out the email address you are allowed to attend ;-) )

Now, what on earth will we talk about??

My role in our company isn’t strictly defined so, outside of my work with the Publications team that I head up, I also get involved with other areas of the company either because I can help, or because there is a vested interest. That brought about the creation of our development community website and more recently has seen me involved in a company wide information project.

The main aims are to provide a consistent set of information to our customers, throughout their relationship with us. So from initial contact right the way through to rollout and future upgrades, we will have a coherent set of information that is updated accordingly and a clear idea of how it will all be communicated to the customer.

This is one of those ideas I’ve long had so it’s exciting to get something like this in place, agreed and set in motion. We are lucky in that we are still a small enough group that we tackle something like this without a huge amount of overhead, although obviously the main reason we are doing this is to help us be more successful.

The model itself is simple, with 4 layers of information:

1. Marketing Information
2. Business Sales Information
3. Technical Sales Information
4. Reference Information

In the real world the layers are not distinct, but by and large the model should help people understand what they should be writing, and what they can re-use across a variety of documents.

Naturally all of this will impact on the technical documentation, with many of the Business Sales level content helping us answer the question ‘Why would I want to use XYZ?’. It’s likely we will share a lot of information with the Technical Sales layer (architectural overviews and the like) but the bulk of work will remain the creation of reference information about our product and its capabilities.

We are still tweaking things, and will continue to do so into the New Year, but the very fact that we’ve started to adopt this approach is half the battle.

The war, of course, continues!

One part of the agenda for our day long “Author-it day” was to consider how we would handle multiple streams (versions) of documentation.

As well as major versions of the documents (3.x) that continue to move forward, we also keep up with changes to maintenance releases (3.x.x). The overhead isn’t too bad, we rarely have to make changes for a maintenance release, but we do need to have the capability to do so and this is where we hit a stumbling block.

Author-it offers the ability to version an object (a book or topic for example). You can have multiple versions of an object but only one can be active. So, originally, our thinking was to create the first (in Author-it) version of each Book and then use the basic “1-up” versioning provided by Author-it.

However, when running through a quick demo of such a system, it became apparent that whilst that model works for major releases (X.x) when you consider the occasional maintenance release (X.x.x) then, very soon, your folders become cluttered with a myriad of versions of objects, none of which are easily identifiable to a particular product version.

So, our solution will be to duplicate objects (copy) to a new version specific folder.

We are switching to Author-it just in time for a new major version of the product line. This allows us to import ALL our existing content as 3.0. From that point onwards each major version will kick off with the duplication of all the Book objects (remember, a book is just a collation of topics for output). Then any topics that change, or are added, for that version will be duplicated (copied) and moved to the new version folder.

Clunky? A little. Manual? Completely. But it’s the only way we can manage our versioning process without ending up with a mess of versioned objects.

Unless, of course, we’ve missed something very obvious.

There are some fundamentals tenets of our profession that are widely accepted. One being that you always need to know your audience before y can begin to understand their needs and so produce the information that they require.

The reason I mention this is because, whilst it’s something very basic and is deeply grained in the technical writer part of my brain, I keep forgetting it.

Let me explain.

I’m currently working on a mini-project aimed at making sure the language we use and the things we talk about through all levels of our product information (from the website and marketing brochures, down to the lowest level of reference information) tell a consistent story. From basic facts and terminology to the concepts we need to convey, it’s important that everyone throughout our company talks about things the same way.

As such we’ve modelled the information into four layers with each layer (roughly) representing a broad layer of user and information types. These types match our engagement model and will allow other areas of the company to understand not only what information is required but, most importantly, WHO the information is for.

I’m writing up a summary document (covering two of the four layers) which will cover the main areas of the product and what language and terms we want to use. The document also outlines the basic concepts of our product, and for each concept describes the level of information expected. This will allow others to build specific documents at the appropriate level, focussed on the correct user type, using the correct language and terminology.

The trouble is that I’ve really been struggling to get my head around it and I was finding it very hard to write the descriptions for each conceptual area. I was mentioning this to a colleague earlier and that’s when it struck me.

I’d forgotten who I was writing for.

The summary document is aimed at internal staff, but is covering the information likely to be required by two different types of reader/layer. As I’ve been developing this information I’d lost sight of that and was trying to write one piece of information for two very different types of user.

So, I’ve decided to split the summary document into two, one for each type of reader and I’m already finding it much easier to structure the information accordingly.

I know I’m not alone when it comes to this kind of thing, that it’s very easy to become blinkered to everything else when you zero in on a particular task. I’ve been working fairly closely with a colleague on this but hadn’t spoken to her for a few days and, without that check in place, I’d started to lose sight of the big picture.

And yes, I know this isn’t rocket science, but hope it may serve as a timely reminder to others or at least let you learn from my mistakes.