A New Normal

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.