It’s going to be a big year for us, both as a company and as a team. We have grand and achievable plans for the product which will mean the working processes for the Publications team will need to change for, as well as multiple streams of work with their own staggered release dates for the product, we are also restructuring our entire information set to improve ‘findability’.

Which immediately prompts a question, how do you improve ‘findability’?

The simple answer is would be ‘in as many ways as possible’ as there is no silver bullet. What may work for some, won’t work for others. However we have to start somewhere and the first thing we can do is restructure the architecture of our information, slimming down the content where possible with an eye to adding new formats of information.

We have already successfully piloted some new formats of information and will continue to roll more of those out for different areas of the product (in essence, these new documents are a high level overview of all the levels of an area of the product, from concept and usage to API implementation), and the signs are that the restructure will go a long way to meeting the needs of our customers.

Having been lucky enough to speak directly to some customers in the latter half of last year, I know that we are on the right path. The challenge will be to keep moving things forward amidst everything else. It’s going to be a busy year and already the analogy is one of a juggler who is keeping things in the air… for now!

“Imitation is the sincerest of flattery.”

It’s a fine line between imitation and theft but, looking around at other documentation sets recently, it’s interesting to see so many common items. Table of contents, numbered lists, signposts and so on. These things exist, and are common, for very good reasons but as we continue to learn about how best to anticipate the growing set of skills our users have when it comes to using information, I’m wondering what will become of these standard, common items we all include in our documentation sets.

Case in point; Recently, whilst, looking at the Atlassian documentation we realised that there were a few nice touches that we could incorporate into our own documentation set. At the foot of every page is a common set of links, something that we think would improve our offering as well.

The only reason we can look to copy that idea is because we host all of our documentation set online (in a similar layout to Atlassian). More and more organisations are going this way yet, so far, most of us are sticking with the old, familiar, tri-pane view we are comfortable with.

Looking at how more and more people use the internet to find information, it strikes me that perhaps we need to be more radical with how we present our information. I’m not quite sure how, but perhaps there is a need for more question and answer style information? Rather than documenting how to use something, concentrate on documenting what to do if it fails? Move away from the table of contents to a more graphical navigation with clear signposting to where information can be found?

Regardless of how, it’s clear that the expectations of people when they use information is changing and if you accept that this new usage model is only going to get more popular then it begs the question… where are the new information interaction ideas? I’m not talking about having a Twitter account, or publishing information to a Wiki, and I think it’s beyond the “every page is page one” view as we seem to be getting away from the notion of anything ever being on a ‘page’ per se, but instead this is a fundamental shift of how we consider, create, and consume information.

Usual caveats apply, of course, as I’m well aware that not everyone will, or should, be looking at this but for those of you who are, what does your future hold? How will you map what you produce now to how your users want to use it, will it be via Facebook, or Twitter, or the new Google+? Do you think you need to consider this? Or not?

The last few years have seen quite a change to our industry and that change isn’t going to stop any time soon so finding answers to those questions may not be easy or, in some cases, possible. However, from what I’ve seen some people are starting to find better ways to allow their information to be used as part of a larger piece, and for me that’s where we all need to start looking.

How is your information used alongside other, competing, sets of information? Do they integrate well or are they still viewed as separate entities? I think we need to include everything from documentation and training material, to sales collateral and the user interface itself. We all need to look at how more and more people are comfortable shifting their lives online and how it’s now common place for EVERYONE to “just Google” to find an answer to their problem. Don’t believe me? Ask yourself how many friends do you have online? and do you trust their opinions more, or less, than your friends when it comes to harnessing specific knowledge?

Quite simply, and this is not a new statement, if you aren’t hooked into the mass of information that is available, you are going to lose out. Which brings me back to my question.

To get properly hooked into people’s online life, I think we may need to change things, so where are the new ideas?

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 recently attended the Glastonbury Festival and, despite the mud and mayhem around me, found myself pondering an issue that we have in our documentation set.

Throughout the week I was at the festival I spent a lot of time consulting a map of the festival site, trying to figure out both where I was and where I should go next. It wasn’t always easy and I got it wrong several times causing us to have to stop at the nearest beer tent, you know, just to make sure we weren’t completely lost.

The signposts around the festival site weren’t always clear, nor particularly abundant) and whilst we coped, it is definitely something they could improve. Being lost is never fun, and at some point over that week I realised this was similar to an issue we have with our documentation.

It was very much one of those thoughts that had probably been percolating at the back of my brain (a dark and dusty place, if truth be told) for a few days. Somewhere in those dark recesses, prompted by frequently being lost at the festival, my brain dragged up a quote from a blogpost I’ve mentioned in this months ISTC newsletter (you don’t have to be a member to receive the newsletter, anyone can sign up and anyone can view the archives).

The quote that had, seemingly, lodged in my head was “every page is page one”; the blog post it’s taken from is well worth a read (it’s linked in the newsletter).

Like many of you, we have a LOT of content, particularly when it’s broken down into topics. Whilst we take care to plan out what content we will be adding to make sure the structure makes sense, we realise it’s not always easily findable. One of the main reasons is that, by and large, most people will find their way into the content via the search results.

Taking the maxim that “every page is page one” makes sense for our situation, but how do we best signpost where the user has landed?

Have you tackled this issue? Do you have a solution? I’d love to hear your suggestions on this.

What are you thinking when you review documentation?

We recently had a short discussion about how peer review, what we thought it was and how it should work. For us, having another member of the documentation team look over your work is useful for several reasons. Whilst we have distinct technical and editorial review stages, having another technical writer look over your work helps highlight things concerning structure, ordering and the killer of all killers, confusion.

Seth Godin nicely captured the reason why this is an important stage of information production:

If you’re building for digital, for a place where you can’t possibly be present to guide or to answer questions, I think it’s vital you have someone who can review your work … Not to make suggestions to make it better (what do they know?) but to share their confusions.

The thing is, it’s easy when you’ve been working on something for several weeks to get too close to the material and start making presumptions. These, inevitably, lead to confusion for the reader. It’s never an intentional thing, and everyone does it (and if they think they don’t, I’d suggest they may not be aware that they do!) but it’s something that we can easily catch.

The way we work, with each technical writer working on a distinct part of the product, it’s reasonable to assume that we can review a document without too much presumed knowledge. It’s not the same as handing the document to someone with no knowledge at all but we can usual spot those areas that may cause confusion.

Typically, these are the things that seem obvious when someone points them out, which a new customer will spot immediately because it leaves them perplexed. Unfortunately those are the moments when confidence in the content drops and, for many people, it only takes one or two instances of these for the documentation to be cast aside, never to be used again.

Catching points of confusion is a crucial part of any review process, it doesn’t really matter whether you have a specific process for it but it is something you should try and make sure you are addressing.

Part way through April and the discussions and planning over the past few months look like they are, slowly, starting to come together.

The plans are ambitious, not only are we restructuring our information offering to make things easier to find, we are also attempting to change the way we document our product. Moving us away from a set of information that covers “here is what our development kit can do”, to content that says “this is what our product does and how you can extend or modify it”. In one way it’s a subtle shift, but the ramifications are still unfolding.

One area in particular will be interesting, namely that we will be asking “why that way?” a lot more than we have in the past. In the past, as we were light on content in several areas, we steered away from such questions where we could, but now we need to tackle them head on which, invariably, will mean we will start to drive some interesting conversations about how our product SHOULD be used.

None of this is, as ever, rocket science, but there is a level of change management that we need to consider.

In the end we should end up with, in essence, an information matrix.

Down the left side will be headings corresponding to the types of content we have (or need to write), and across the top will be a list of the areas of the product we document. I say “will be” because we are still trying to fully understand what those areas are, and to make sure that the terminology we use will be understand and used consistently across the company. Once that matrix is in place, we can audit what we have and see where the gaps are.

Thankfully, once we understand the new structure, the act of restructuring the information will be easy. The joys of single source, topic based authoring!

I won’t, however, mention the third level of complexity we are trying to tackle as I’m not quite sure I’ve got a handle on it yet. Suffice to say that we need to make sure the new information structure we decide on within the product documentation, also needs to fit into a wider piece that is being introduced to our developer community website (same basic idea though, creating landing pages on ‘topics’ or ‘product areas’ to direct users to product documentation, elearning material or support notes).

It’s a bit like doing a big jigsaw and at the moment I’ve only just managed to finish the outline.

If there is one phrase which should set off alarms in the mind of a technical writer it’s when a developer says “Ohhh but they wouldn’t use it like that…”.

Because, as I’m sure you all know, they will.

I am currently working with a few people to try and pull together a solid set of product usage recommendations. We provide an SDK and a feature rich application built using our own technology, and that application is extended and configured for specific uses. There are plenty of hook points in there and, for the most part, usage follows accepted patterns. However there is always the time when a certain component is bent and twisted and used in a way we hadn’t expected and it’s these instances that we are trying to understand and capture.

We get a view of them by exploring edge cases when testing, but it occurred to me that there is still one thing that can catch us out. Our old nemesis, ‘presumption’ (which is usually coupled with it’s friend ‘common sense’).

So now I’m on red alert for any statements which are based on presumption. Sometimes they are right, but it’s the times when they are wrong that we need to explore them, capture them and help our customers by giving them some frame of acceptable usage. It’s not an exact science, but even just pausing to have those short conversations seems to be helping.