I’ve waffled on about single source and our plans for long enough so, as we are finally starting the process itself, I thought I’d capture some information as we go along. However, it’s probably good to set the scene, so I’ll cover that stuff first. Over time you’ll be able to see all the posts related to this work here.

By this point we have completed analysis of our content (looked at a few sample chapters and identified the main types of content that we have), we know the problems we face now and in the future (lack of intelligent structure, no re-use of content, slow turnaround, and limitations around the tooling) and what we need to do to fix them (rewrite/repurpose the information appropriately). We know the tool we are going to use (Author-it) and are confident it is a best fit to our needs. Which leaves one further question.

When do we start this work?

Which is where we are now. We have the tool, and I’ve just set up our content database. Next up we are looking to pull together some high-level scenarios for how our product is used so we can match those to the new structure for the documentation. Yes, that’s right, we are also considering restructuring the documentation. Well, why not, we’re having to chunk and import the information so may as well get the output structure correct as well.

The scenarios should also help us decide what content to migrate first as there is little value in migrating content that doesn’t need to be updated or re-used. The idea of using scenarios came from one of the team and the more I think about it, the better a fit to our needs it will be as it should allow us to build better documents and help systems, as well as focus the migration process on the areas of highest priority.

Ultimately it may turn out that we never migrate some areas of our legacy content. The only reason would be to reduce the reliance on an ageing toolset but even then it will be a decision of cost.

As with most projects of this type, where you have a long timescale, there are other concerns we need to take into account which include rebranding the company and a push (which I’m involved with) in getting a company wide information strategy in place. A lot of that will drive other work as we are aiming at gaining better consistency of information and messaging across all the areas of our company which is yet another reason why our single source solution will be a great asset to the company as a whole.

The current plan is for the rest of the team to work on new information purely in Author-it, whilst we create Content Plans to make sure we migrate the correct information in time for the next release. To allow the team to continue to work I’ll be handling all of the migration so, probably some time next week, all work in FrameMaker will stop and we’ll take a ‘cut’ of the documentation which will, from that point onwards, be our main stream of work.

The Content Plans should allow us to rebuild the documents we need, slotting in the new work that the team have been working on… seamlessly… I hope!

Fingers crossed, the countdown has started.

(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.

I’ve waffled on about single source and our plans for long enough so, as we are finally starting the process itself, I thought I’d capture some information as we go along. However, it’s probably good to set the scene, so I’ll cover that stuff first. Over time you’ll be able to see all the posts related to this work here.

With a most recent product release almost out of the door, our thoughts turn to the next few months and, finally, beginning to move our content to Author-it. During our weekly team meetings, and across several shorter planning meetings in the past months, we’ve covered most of what we think we need to have covered.

However, to be sure we’ve decided to have an entire day, locked away in a room, to go over the basics and properly plan the content migration. We have a provisional agenda but it’ll be a fairly open session for most of the time, as long as we can drive out actions I’ll be happy. I’ll be shifting my PC into a meeting room and running it on a large screen so we can actually try things out whilst we are there.

So far the agenda looks something like this:

• recap the basics - what is reuse, what topic types do we have
• EXERCISE - take a sample chapter and walk thru the import method
• where will the imported topics live? (we have a structure, is it right?)
• how do we handle maintenance of different versions of the guides?
• EXERCISE - working practice - RID needs changed from 2.7 through to latest - how do we do that?
• output templates - what do we need?
• working with graphics - agree best practice
• what import templates need to be created
• who will import what?

The two exercises are there to help us troubleshoot any potential issues that may arise in everyday usage. We’ve already had discussions around topic types, the structure of the content within Author-it and I think we’ve covered everything but the main underlying aim of this day will be to flush out anything we’ve missed, or highlight any minor niggles that we aren’t aware of yet. Hopefully we can answer all of our questions (or at least understand the questions properly) and move forward from there.

Of course the REALLY big question is whether I bring in doughnuts or chocolate biscuits for the day…

Back from a week in Spain (weather was lovely, as was the cerveza and tapas!) I’ve taken some time to look into some suggestions for screen recording.

Part of the developer community website we have was always aimed at providing online video tutorials showing the latest features. However we’ve had acres of issues getting these produced. The recording usually goes ok but editing them and getting them into a format that is acceptable for the website seemed to be causing us problem after problem.

Having checked out all three suggestions, Wink, Demobuilder and Camtasia Studio I have to admit (and you’ve probably already guessed from the title of this post) that Camtasia Studio blew me away. It’s a very slick piece of software, brilliantly designed to lead you further into the complexities it CAN offer without dazzling you with options the frist time you fire it up.

One of the best features, the one that took me by surprise, is called SmartFocus. As you click around the screen it zooms in appropriately and only, rarely, missed a beat in the few demo recordings I took. It’s very impressive, and once you get into editing the recordings, splitting them up, adding transitions, captions, callouts… well I’m sold. As will my company very soon (the purchased order has been raised).

Thanks to all for their suggestions.

If you are looking for a very simple and quick way of recording a screen demonstration (I’ve run up to about 30 minutes without issue) then go download the Camtasia Studio demo copy. You can try it for 30 days and if you are in the market for software like this then definitely give it a look.

Hell, if you have 30 minutes free, download it, install it, record something and watch the playback. You’ll probably start to wonder what you COULD use it for in the future…

Note: I’m not being paid for this, just the opinion of a very impressed first time user.