Month: December 2012

I’m currently cruising high in the sky above the USA, on my way from San Francisco to Boston. It’s part of a whistle stop tour of two of our offices here which have teams of software engineers, architects and product managers (no technical writers though) that are building part of the product we will be shipping early next year.
During a chat with a couple of the product managers there was an interesting revelation. In describing the approach the team takes when it comes to writing documentation, the two product managers both smiled with relief when I said that we didn’t really spend much time on simple procedures, instead we try and concentrate on the why, on decision support information. We work with the support team to catch any areas of the product which are causing problems with a view to improving the documentation in that area as well, and overall we understand that the people using the development platform are usually smart, technically minded people, so we ask smart, technical questions of our development team.

The thing is, that’s not really a revelation for me. It’s something we’ve been doing for quite a while now, so much so that I can forget that for a lot of people the term “product documentation” is often seen to be fairly rote task-based, step by step procedures with little in the way of explanation.

Whilst that’s handy when you are still learning a new product, pretty soon that information becomes useless.

Thinking further, the decisions we are making during our current restructure project reflect this thinking as well. One step that was very interesting was asking some of the given audience of our product (our own developers and professional services staff) to do a card sort of some of the topics. They all have a mental model in their heads of how the product (and so the supporting information) is structured. Anything outside of that was a real problem for them to deal with.

It’s that problem area where asking why, and producing supporting information that helps the user understand how something works is far more important than simply telling them which buttons to click.

Since our companies merged we’ve had a lot of discussions and sessions to help the other engineering teams get up to speed with our platform, it’s been a bit of a rude awakening if I’m honest, as there is a lot of knowledge still floating around in the heads of some of our developers.

So it looks like the task next year will be to change that, to make information and the dissemination of it much more a key part of the software engineers thinking. I’m not quite sure how we are going to manage it but I do know that we have to create a new normal where information sharing, product information and an understanding of who is using our product needs to be much more front and centre in our thinking and our working processes.

For the last few months, the team have been rebuilding and restructure our content. We’ve ditched the idea of ‘guides’ for now (although we will revisit those early next year) and after a lot of hard work we are starting to build out new groupings of content. The process has involved a lot of analysis, and we’ve had a few nice little wins on the way, for example; we started using Mindmaps as a way to visualise the content and will be rolling them out as part of our normal planning in the future.

This is the 1000 feet view of what we are building:

And that’s not quite everything…

It’s been a long journey to get to this point, and I admit I have some fear that all of this information is too big to know.

However, we know that the majority of people use search to find content in our system (we publish to WebHelp and host on a developer community website) so I’m confident that with our new structure, which includes a lot more signposting and navigation, the content will be much more usable.

One of the mindset changes was moving away from worrying about product manuals as a construct, it’s very freeing but also quite scary. That said, there has been a lot of work in validating the approach we have taken so we are confident in the approach, even though there has been more work than we originally anticipated (do not under estimate the creation of navigation topics).

Will it work? I think it will, although I’m aware there are likely some gaps that will be exposed that we will need to fill. We will try and plug those as we go along of course, but once this is in place we can start to look at other content. As I mentioned previously, we provide other content types (PreSales overviews of the product, for example) and at some point next year we will go through this exercise on that set of information as well. Thankfully it’s much smaller!

I don’t know about you but I’m getting fed up trying to make everyone realise the value of what we do. Technical Communicators of the world unite!

Why is it so darn hard? Isn’t it obvious? We live in a so-called “information age” after all, so why is it such a struggle to get the message across?

So, for the meantime, I’ve stopped.

My team currently has a separate stream of work looking at how we get better at PR and whilst that runs its course I’ve decided to deploy a different tactic, one which has fallen into my lap. No more will I go cap in hand to department heads, no more will I try to coax, nudge and cajole others into understanding why product information is so important. I won’t roll out the usual reasons, and I will save my “part of the product life-cycle” spiel.

You see, we’ve been receiving requests from different parts of the organisation, based on some work we did in the past. Lots of people are looking for help. At the moment, all of the team are busy but I’m going to pick one of the requests and find a way to get it actioned. That way we will get a quick win and increase our profile a little (it really is great to be part of such a good team, their work speaks for itself) and it should give us an ‘in’, an opportunity to build a relationship with a different part of the business, learn how they work and in time expand what we do as part of our service to them.

Land and expand. Simple really.

At present I know there are many areas of the company producing content. I also know that many of them would benefit from our input, just as I know we don’t currently have the resource and, without a lot of up front research I’m not sure I would be able to guess at what resource would be required to cover the current requirements. Creating the business case to expand operations would take time, and even then a lot of the effort goes into educating people as to why consistent, reliable, re-usable product information is a “good thing”.

With that in mind, getting a foot in the door (landing) before getting involved and agreeing a level of delivery for the future (expanding) seems the most sensible way forward. It allows us to get a feel for where we can best be involved and over time we can increase our influence, and standing, within the company.

Now, where I can buy some ninja costumes?