In the New Year we are instituting a No Talking rule in my office. If anyone has a question, they have to write it down and pass it to a colleague who will then write down their response. This should cut down on the amount of chatter and conversation that, obviously, is having a huge impact on productivity.

There will be no more talking in our office, the conversations will stop!

I am, of course, joking.

What I’m actually pondering is how to extract the casual knowledge that currently exists in the heads of the development team. The little snippets of information that take seconds to utter when prompted by a nearby colleague, but which remain out of the grasp of the product documentation and thus are invisible to anyone not sitting in our office. You know the type of thing:

“Hmmmm, hey Alice, my build failed with error 4932, any idea how to fix it?”

“Ohh sure Lewis, just set property 73 to false and it should run just fine.”

The above names have been changed to protect the innocent.

This kind of conversation happens everyday, across the breadth and depth of our (very large) product and, as we have development teams around the globe, it is a real problem and one we need to solve.

The No Talking rule might sound ridiculous but it may be one way to help people realise just how much information they impart to each other, face to face, that isn’t captured anywhere else. That’s the theory at least.

I work with smart people, they are friendly, helpful and professional. They go the extra mile and genuinely want to do a good job. I’m not just saying this but they are one of the best groups of people I’ve worked with, but that doesn’t change the fact that they way they work is flawed.

Ultimately the challenge will be to change the culture, just enough, to be more info-centric. For example, if the software build system breaks, the developers fix it, yet it seems obvious to me that our information channels are broken and my perception is that they don’t care enough to want to fix it.

How do I get them to invest in this idea? Talking to my girlfriend she rightly suggested that one method that might work would be to pitch it as a time-saver. If every developer was to count the number of questions she was asked over the course of a week, I think they’d all be surprised at the number. Whilst not all of the questions would be something that needs documented, I’d warrant a fair number would be. As I said to a during a discussion with a couple of team leads last week, I’d much rather my team was inundated and overrun with requests to add information to the product documentation, at least that way we’d know the size of the problem.

So maybe I will suggest a no talking day, or maybe there is another mechanism out there that the developers will buy into. Maybe the first step should be to ask them what they think, are they even aware this problem exists (I’m sure they are, it’s just not the most pressing problem in their day to day list).

Regardless, one way or another, it’s something we need to fix, preferably without stopping the conversations.

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!

The modern day technical writer, in fact I think we’ll go with technical communicator for this on, has a myriad of tools at their disposal. Be they authoring tools, publishing formats, or ways to collaborate, we are spoiled for choice. I can write content and make it available to the world in mere minutes if I so choose (and I do, frequently, you are reading it).

Of course, there is more to our job than the tools of our trade, so much more that at times I think we can forget that our value lies elsewhere and if we are forgetting that, can we really blame others for losing sight of it too? We are more than our knowledge of Microsoft Word, but I fear that’s not always apparent.

Working in a software company, I hear talk of the ‘quality of the code’ frequently, thankfully I hear similar comments about the product documentation, so where does the disconnect occur, how do our fellow professionals move from “those are the people who produce good quality product information” to “anyone can write product information” and, more importantly, how do we change that notion?

Part of the problem is that anyone can easily create and share information, better than that, they can collaborate with the author on that content. The people using the information can ask questions of the author directly, add their comments and even edit the content if it’s not correct. This is not new, Wikis have offered similar functionality for many years, yet somewhere along the line the value placed on information shifted from the quality of the content, to the functionality surrounding it.

• Can I access it easily?
• Can I leave a comment?
• Can I send it to someone else?
• Can I port it to another platform?

Some argue that information as a commodity raises the bar for us all, that by placing a value on information it allows us to be part of discussions we’ve struggled to gain access to in the past. Whilst that may be partly true, somewhere along the line we missed a grand opportunity.

Treating information as a commodity hides the real value and, worse, it places the high quality information we create into the same jumbled marketplace of content that we are all all too familiar with. As a commodity we have become just another coffee maker. Some people will seek out the best of such things, but the majority will not, they will seek the lowest cost and presume that, as it comes in a box that says ‘coffee maker’, it will meet their needs.

How do we change this?

The short answer is, we can’t. The horse has flown the cowshed (?!), the battle is lost.

However, that’s not to say the war is lost.

Good quality information will bubble to the top of the pile eventually. If your information is in a small pool, this will happen sooner rather than later. If you are concerned only with an internal audience you can help this happen by reaching out to other parts of your organisation to make them aware of what you are doing. If your information is in a larger pool, and you have to contend with other ‘google-able’ sources then you will need to do some leg work, some P.R.

This is not a new scenario and the very things that give us flexibility and power are also the things waiting to plot our downfall.

Information is a commodity. There is no escaping that fact.

But we are craftswomen, craftsmen of the highest order, and our knowledge and approach to information gives us an advantage that we shouldn’t be afraid to push home. Yes, all that other information is good, yes I’m sure it comes in handy now and then, but our information is something you can rely on, something that you can trust. It is honed, refined and delivered by experts.

Our information is not a commodity. It is a differentiator.

The sooner we all understand, and believe that, the better for us all.

What happens when one company acquires another? How do you merge departments, working practices, content? That’s the challenge that lies ahead for me as my company was recently acquired by Kana Software.

We are still in the midst of integration planning, figuring out how to take the best parts of both product sets forward, and I’ve started to look over the documentation created by our counterparts across the water. It’s immediately obvious that we will need to make some compromises. Firstly in tooling, we use Author-it they use FrameMaker, and then in style (both writing and content delivery).

We’ve been moving to a more article type deliverable, focussing on explaining the reasoning and thinking behind a product feature and only providing How To style information when needed. From what I’ve seen our counterparts, whilst they have a good mixture of information, they have a lot more in the way of How To style information.

We had already kicked off, shortly before the acquisition was announced, started an entire overhaul of the structure of our product documentation. The early results are looking good and should make the entire product information set much easier to use, and it’s been timely as it will allow us to be confident that the information we are taking forward is the best we have, is logically structured, well researched and written.

First things first though, and I’m setting up some calls to talk to them, to understand how they work day to day, why they made the decisions they’ve made and to explain the same from our side of things. Somewhere in the middle lies the future, the path forward to a combined set of product information.

It won’t be easy, we both come to these discussions with a large amount of information, but I know we are all up for the challenge!

Working in a team that isn’t heavily invested in documenting requirements and specifications (we usually have a starting set of such things but these soon fall out of step as development evolves) makes it a challenge to know both what is being added to the product and whether it needs to be documented.

The development teams recently adopted JIRA and whilst the additional information helps I fear it may give us a bigger problem. As we will (should?) finally have a clear picture of everything being added to the product, will it be too much for us to handle?

At present the Publications team have two very large products, with a complex API and code base which is all evolving and which needs to be documented. We cover a mix of SDK style documentation, reference information as well as procedure based topics and many conceptual pieces. We don’t document all of the product at the moment but it’s fast becoming apparent that deciding what NOT to do will be a vital skill as we move forward.

We can’t, and shouldn’t, document everything but a firm focus on making sure we are providing the most value (bang per buck!) helps us make better decisions about what we can ignore, and what our customers really need.

How do you cope with the ever increasing pace of development? What don’t you do?

Ever wanted to just throw everything away and start over?

I’ve been tempted by this notion recently and, whilst it may seem a bit ill-conceived, part of me does wonder what would happen if we just, quietly, started removing some parts of our documentation.

In fairness, we’ve done that in the past. Our Development Kit has many aspects to it but, applying that old favourite 80/20 rule, we realised we didn’t need to maintain or even publish documentation on every single function point.

One of the reasons for the current line of thinking is that, quite simply, we have too much information. There are too many places to find information about our product, so we are refocusing and slimming down our offerings to make it easier for our customers.

This is a change of direction for us. When I first joined this company, to start building a team as there were no technical writers with the company when I joined, I inherited a lot of legacy documentation, not all of it particularly useful (my oft quoted example was finding one single page of documentation for a particular Tool in the Development Kit. One page for an entire tool packed with functionality, that you launch in the same manner as every other Tool in the Development Kit, which told you … how to launch the Tool. Useless much?). The challenge on joining was to improve the quality and coverage of the documentation.

And we’ve been very successful! We have a rich set of information available, but over time it has, as it always does, started to degrade. We have added more and more and, whilst we have consolidated where possible, the pace of product development here means we are usually hanging on to the coat tails of the next release.

So, with some changes to responsibilities and a shuffling of resource we are now in a position to take stock and start removing content and completely overhaul the structure of what we deliver. That will help improve findability (our main aim) and by focusing on the content that is really needed we can improve the quality as well.

It may also mean a change of authoring tool to support the outputs we want but more on that, later.