I’m procrastinating.

I’ve reached a certain point in the work I’m doing that requires the completion of a very large planning spreadsheet. I’m currently looking at all of our content with a view to restructuring it to fit better with the way our customers work hopefully making it easier for people to browse the content.

I’m taking an organic approach for this first pass. Taking the chapters in each current guide and rather than forcing them into a pre-existing structure, I’m making an educated guess as to where they might live in the future. Once that is complete I’ll take the list of suggested locations, give them a quick sanity check and mockup some examples and take them to some of our customers.

This is all part of a move away from monolithic PDFs, towards a more focussed set of content that is available online. However, whilst we are concentrating the bulk of our thoughts and efforts on our HTML based “Knowledge Centre”, the need for PDFs remains and hopefully the new structure will help keep the set of published PDFs much leaner by splitting out only the information that people need to be published in that format.

At present it’s definitely one of those jobs that ‘just needs done’. It’s not hugely challenging, nor particularly enjoyable but such is life. The end goal will, hopefully, just the means and all that.

It’s still got a way to go before it best my ‘most boring job’ though. That one involved reformatting hundreds of single pages of content, all held in separate Word documents as part of a migration process from one tool to another. It only took a month or so…

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!

Last night, around 3am, I woke up. I lay there in bed wondering why I’d woken up and as my mind started to churn I realised I was very very awake.

In flooded four things I’ve been thinking about for some time, all of which are related but I couldn’t quite make the connection. Last night I cracked it. Maybe.

I’m still thinking it through but here are the four items in question:

1. Single sourcing our documentation – and recent discussions with other areas of the company who could benefit from the same approach.
2. Company Information Strategy – a simple pyramid based model that allows everyone creating content to ‘map’ their audience appropriately and which should start to help with consistency of terminology and messaging.
3. Document Management – there have been some murmurings about this from a few people and it’s likely to fall into my lap.
4. Requirements gathering – we’ve recently rolled out a new process which should lead to better requirements for each project build.

All of these are tied together, and if planned properly can feed off each other. Naturally there is quite a lot involved with all of the above and I’ll be revisiting items one and two in the coming weeks.

Ohh and I’ve still to pull together a slide deck on “selling our services”, which involves all of the above and more. Once it’s ready, I’ll share it here.

Exciting times ahead.

I’m guessing that you don’t want to miss that landing pad because if you do you’ll end up ditched in the ocean, floating around aimlessly and with no real idea of what to do next. Can you imagine how horrifying it would be if that happened? Floating there, unable to get back to land and with who knows what swimming around underneath you…

Yet this is the predicament that many users of online help find themselves in, having strayed into the online help they have been cast into an ocean of information with no real idea of how to get back to shore. Ohhh sure, we tell ourselves that the there is an easy way to get to the information they want through our carefully crafted Table of Contents, or perhaps a more direct route can be navigated using that Index you toiled over for hours, or better yet if they use the Search functionality they’ll find what they want. Right?

And, ultimately, yes these mechanisms work. If you know how an Index is structured you can quite quickly navigate to a keyword that probably matches the information you are searching for and should, hopefully, take you almost directly to the very help topic you need. Same goes for the Table of Contents although they are a little more prescriptive and you need to know what you are looking for to be able to find it, and of course the Search will provide you with several help topics that are, probably, what you are looking for.

Meanwhile the sharks have gathered and are nibbling at your feet!

At the UA conference last year, Matthew Ellison gave a presentation on what he termed “Keystone Topics” and in the Summer edition of the ISTC Communicator magazine (again, chock full of good stuff, it’s worth the price of membership alone if you ask me) Paul Filby covers something similar, outlining how to provide “The perfect help-system landing page”.

And so, with all of that in mind that is my task today (yes, a Saturday).

The concept is simple enough. You create a single topic that will be displayed to the user when they bash our old friend the F1 button. That topic is unique to the help system and, based on context, can be used to display a smarter set of links to potentially useful information. If you have the means you could display the most commonly viewed topics or, as I’m doing, you can point to the start of several paths covering the most commonly used areas of the product.

I don’t expect to get ours right the first time round, but hopefully the concept will work. I’m including a small addition to the foot of each such topic, asking users to contact us if they have improvements. It’s only on the landing pages but I’m hoping it might drive a nice little cycle of innovation with direct feedback from the users driving the content of the landing pages in the future.

Hopefully the landing pages will give our users some where dry to stand and survey the land a little, with clear signs to help them get to where they want to go.

When I get to the bottom
I go back to the top of the slide
Where I stop and turn
and I go for a ride
Till I get to the bottom and I see you again!!!!

Ever get that feeling that you’ve been here before?

I write this blog post with haste as I’m halfway through the penultimate week of a particularly arduous project. Not only are we releasing a new version of the product, but we are completing the first major stage of our move to Author-it.

Overall the migration has been pretty painless. There are still some Word templates issues to work around and getting to grips with Variants has still to be tackled, but overall we are pretty happy with our choice. The only major gripe we have is partly our (ok, MY) own fault, and it’s here that I’ll offer the most valuable tip I can.

If you are migrating legacy content to Author-it (we were moving from Structured FrameMaker), make sure you thoroughly test and check the import settings. Time constraints had me rush this stage and we ended up paying for it, spending far too long cleaning up rogue topics than we had planned. Every cloud has a silver lining though, and it does mean that the documentation is now far more consistently written and styled than it had been. However, going through some 5000 odd topics by hand wasn’t the greatest use of our time!

Soon we will be looking to how we can leverage the output to provide better access to information, feeding into the developer community website we have already built, and improving how we deliver information alongwith our product set.

For the former we have taken some inspiration from the presentation by Rachel Potts and Brian Harris (Red Gate Software) at last years UA Conference, titled Delivering Help in a Support Portal. For our implementation the Publications team will take the lead, and it’ll be interesting to see where it takes us. Web 2.0, anyone?

We will also be looking to provide better online help by introducing Keystone Topics, as suggested by Matthew Ellison. Author-it should make these topics, which are the first topics the user lands on when they start the online help and which provide sensible links to common information (rather than just providing repurposed user manuals), very easy to build.

Two of the team will be in Cardiff for the conference this year so it’ll be interesting to see what we learn there and how we can really start to leverage Author-it in more and more powerful ways. I’m definitely keen to start innovating what we do and, in a few weeks time, we won’t have any further barriers to stop us.

One of the more popular posts on this blog is titled DITA is not the answer and, whilst things are certainly moving forward, it’s a little sad that it is still valid.

A recent comment on that post suggested that it’s not just DITA that is lacking, it’s the working realities of single source that is flawed.

Well, that and the fact that I keep referring to single source when I am actually meaning content reuse (for you can have one source for everything but not reuse the content anywhere).

You can read the full comment yourself but the relevant bits are:

I have never seen single sourcing work. Maybe a single author who knows the topics thoroughly enough to reuse, or a tightly knit group of writers synched up at the same level.
…
The only place we are going to reuse content is in web mashups using semantic markup once the content is in the cloud.

It’s an interesting view and one which touches on something that has been on my mind these past couple of weeks as we are in mid-migration towards our single source solution.

Just how do you coordinate a team of writers, working in discrete areas of the documentation, with a large number (3000+) topics?

There are a number of ways we are tackling this and only time will tell if they are successful. Firstly we spent some time discussing how best to structure the source topics. Do we group them by product area? By topic type? Or some other arbitrary method?

We decided to group at the highest level (the top level folder) by user persona, and below that we grouped topics in accordance to how they are viewed from the product, so development kit wide ‘Events’ are stored in single folder, where as topics for a specific piece of functionality in the development kit are stored in their own folder. Your system will be different, of course, but this method suits our needs.

After that we need some way of knowing both what type of information a topic contains, as well as where that topic is used. We are not authoring in a DITA specific environment but decided to model our topic types on the DITA model to future proof us as much as possible (we are using Author-it which will export to DITA XML should we need it in the future). We have different templates for each type of topic (Concept, Procedure, Reference and so on), primarily to allow us to identify a topic (by default, Author-it shows which template a topic is using).

That leaves the final piece of our puzzle. How do know where a topic is used? This is more than just a list of which deliverables the topic will appear in, it also has to hint at the context of how the topic is being used.

Does any of this mean that we are more likely to reuse content? Not necessarily but it should give us a fighting chance, and once we’ve updated the content plans for all of our deliverables we will start to really see the benefits. Those content plans were the very things that suggested we could reuse content across multiple deliverables and I’m certain that, with a bit more analysis, we’ll get further gains.

Can single source and content reuse work? Of course it can. There are plenty of good examples out there and they all share one thing in common, something that isn’t really broadcast by the vendors; content reuse from a single source takes a lot of hard work.

But it is possible.

Recently Scott Abel posted a heartfelt plea to get people all psyched up about how to better promote DITA to the rest of the world. He backs the idea of the DITA Adoption Technical Committee, stating that:

“we need excellent communicators with the gumption, know-how, and network to get the word out about the many ways DITA impacts the world and those who live in it.”

I’m a fan of DITA and as I read his post I could feel myself getting quite excited, he makes some excellent points about finding real world examples of the benefit DITA can bring but something just doesn’t quite fit. It’s taken me a while to get my head around this but, isn’t a standard supposed to be a technical implementation detail, not the main focus of life changing events? Ahhh but wait, Scott agrees:

“DITA cannot be the focus of DITA adoption and publicity efforts.”

OK, so we can’t focus on DITA itself and, as Scott rightly points out, the software vendors will soon turn discussions away from DITA and towards their own feature set, so we can’t look there for an example either. In fact it’s not until the latter half of the post that Scott really hits on what he would like us to do, and in my opinion the following sentence is the key to his entire argument:

“Let’s strip away all the noise that prevents normal humans from understanding what we technology addicts find so wonderful about DITA, XML, content reuse, content management, dynamic content, personalization, and so on. … The focus has to be on the human impact. How does DITA help make the world a better place? How does it make it possible for humans to interact with one another? How will it help everyday humans in their everyday lives? How can it help governments better serve their citizens?”

Big questions.

Whilst Scott is aiming at a top-down view of the world, there are lessons there for those of us who are trying to push these things upwards. Selling DITA as the fundamental part of a single source solution now seems a little odd, particularly when most business cases are focussed on ROI and the whys and wherefores surrounding the choice of tooling, so if you can detach the tool from the business case, and focus thinking on the benefits of DITA (rendering the tooling generic rather than specialised) you can start to really crack the story behind how adopting DITA as a content standard will benefit the customers of your company, THEN you have a much more powerful argument.

So, if anyone has any answers to those big questions, do let me know…