For a while now I’ve been watching video presentations from the likes of the TED and GEL sessions. Largely these are delivered by people who are at the forefront of their field or who challenge common perceptions with some unique thinking.

The TED (Technology, Entertainment, Design) sessions can be a bit random but they are always entertaining as they are delivered by people with a real passion for what they do, to an accomodating audience, by experienced presenters. It’s a good combination.

The GEL (Good Experience Live) conference is, as the name suggests, focussed on good experience. Which begs the question “What is good experience?” but there are others far better versed in giving an answer to that question so I’ll leave them to it (you may find some answers on the conference website).

It was on the latter website that I recently watched a presentation by the head of OXO (Note for UK readers: this is an American housewares company, not the makers of gravy cubes). Alex Lee, President of OXO, delivered a presentation featuring some of their products and outlined some of the guiding principles they follow, one of which he stated as:

“Helping people without the stigma of being helped”

Sound familiar? Have you heard something similar when discussing why “no-one reads the documentation”?

I think the first person who I heard mention this was Matthew Ellison at one of the Digitext Help Conferences. It was early in my career and did strike me as quite fundamental and a little bit hard to fathom. As a Technical Writer my main goal is to make the life of the user better (to give them a good experience when using the software by aiding them through those process), so to hear that there was an issue like this that blocked someone from accessing the documentation I was so carefully crafting was quite a shock.

So how do we, as technical communicators, deal with this issue? How can we help our users get past that stigma?

I’m interested in hearing your thoughts on this, I have a couple of ideas in mind but nothing firm. Is this something you try and cater for in your product information? Do you have any way to influence this in other areas of the product? What techniques have you deployed that help get users ‘into’ the documentation? Is there much of anything that we CAN do??

I’m off to dig about for any research into this area, feel free to leave your thoughts and ideas in the comments, or email me direct.

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.

How long is a piece of string?

It’s a common question and one I’ve occasionally used in reply when asked “We are building this new thing. How long will it take to provide some documentation for it?”

Estimating the amount of time it takes to write documentation is tricky as it relies on many differing, subtle, factors and, for many people working outside of a highly regimented and heavily project managed team, it tends to boil down to a mixture of guesswork and experience.

However, it’s not impossible to come up with a more reasoned estimate as long as you don’t mind doing a little planning. Although, to be frank, if you aren’t planning your work, you can probably stop reading now and go find a copy of Information Development: Managing Your Documentation Projects, Portfolio, and People.

So in the spirit of sharing, I thought I’d cover a planning aid I’ve used in the past and have, very recently, uncovered again. It’s focussed on topic based writing, so can be used whether you are single sourcing your content, or not but I should caveat that it was created with single sourcing your content in mind. This is based on a system I’ve seen elsewhere, alas I can’t recall the original source, if you know where this comes from, please let me know. I’ve adapted it for my own needs but happy to credit the original author (Hackos?).

The idea is simple enough. You break down your planned content into topics, with a topic defined as a discrete amount of information that shouldn’t take more than a couple of hours to write. Then, when you add in time for review and rewrite, you can take an educated guess at how long an ‘average topic’ takes to complete. So, for discussions sake, let’s say an average topic* takes around 5 hours to complete. Nothing revolutionary so far.

Each topic is then scored against four criteria, with the scoring used to add/subtract an appropriate level of variance:

1. Difficulty of Topic – do you know what you are writing about or is it brand new? Is it a simple topic or something complex?
2. Scope of Topic – Does the difficulty dictate that a lot of content is needed? Or is it a short topic of fixed content?
3. Availability of Information – are you updating an existing document? Do you have a specification to work from? Or are you having to write from scratch?
4. Access to SME – do you have good access to a Subject Matter Expert? Do you have limited access only? Or none at all?

Each topic is scored, from 1 (long, hard, complex) to 5 (short, easy, simple), against each criteria. An ‘average topic’ would score 3 for each criteria and won’t affect the estimate from the standard 5 hours. Scoring the topics this way allows you to factor in a level of variance, so a difficult topic with a large scope which has no information available and for which you have no access to an SME, will score lowest marks (all critera score 1) and has the highest level of variance from your standard topic estimate.

The criteria are fairly high level and you could certainly expand on these for a more granular approach but I’ve found that most issues can be assigned to one of the above criteria and that keeps the estimation as simple as possible.

The variance can then be calculated (again with an estimated time) so that you can adjust the time it takes to complete the topic, for example:

1. Score 1 – variance of +2hrs per criteria
2. Score 2 – variance of +1hr per criteria
3. Score 3 – zero variance
4. Score 4 – variance of -30mins per criteria
5. Score 5 – variance of -1hr per criteria

The figures given above are, also, estimated. You’ll note that the higher scored (and therefore lower variance) topics don’t ‘gain’ you proportionately the same amount as you lose to the lower scored (higher variance) topics. The reality is that, no matter how simple the topic, they still take time to create (increasing the gain numbers could result in a topic taking less than zero time to create!).

So a long, complex and hard topic, with little to no information and no available expert will will score 1 across the four criteria and so add 8 hours (2hrs per criteria) to the estimated completion time for that topic, taking the estimated total for that topic to 13 hours.

Flip the example round, a short, simple topic which comes with sufficient supporting information and an SME sitting on your desk to help you write it. That topic would score 5 for each criteria, and gain you 4 hours, meaning the estimated total for that topic would drop to 1 hour.

Now, the obvious thing to do would be to create a spreadsheet for all of this, that allows you to simple add in your topics, score them against the criteria and calculate the total estimated time (and whilst it’s at it, it can add in a level of contingency too). Which is exactly what I did.

Download the estimation spreadsheet (6KB ZIP file, contains Excel Spreadsheet)

The spreadsheet is annotated to help you understand it, and includes two additional columns which let us track when a topic was added to the spreadsheet (either as part of the initial planning, identified during the review cycle, or because of a change in product scope). All of the calculations are basic arithmetic so feel free to have a poke around and try this out.

It’s not an exact system, but that’s why they are called estimates and if nothing else it helps my team plan what they are writing about which, sometimes, is more valuable than the estimates themselves.

* this is probably the most contentious part of this method and may take some refinement to arrive at a workable number.

My role in our company isn’t strictly defined so, outside of my work with the Publications team that I head up, I also get involved with other areas of the company either because I can help, or because there is a vested interest. That brought about the creation of our development community website and more recently has seen me involved in a company wide information project.

The main aims are to provide a consistent set of information to our customers, throughout their relationship with us. So from initial contact right the way through to rollout and future upgrades, we will have a coherent set of information that is updated accordingly and a clear idea of how it will all be communicated to the customer.

This is one of those ideas I’ve long had so it’s exciting to get something like this in place, agreed and set in motion. We are lucky in that we are still a small enough group that we tackle something like this without a huge amount of overhead, although obviously the main reason we are doing this is to help us be more successful.

The model itself is simple, with 4 layers of information:

1. Marketing Information
2. Business Sales Information
3. Technical Sales Information
4. Reference Information

In the real world the layers are not distinct, but by and large the model should help people understand what they should be writing, and what they can re-use across a variety of documents.

Naturally all of this will impact on the technical documentation, with many of the Business Sales level content helping us answer the question ‘Why would I want to use XYZ?’. It’s likely we will share a lot of information with the Technical Sales layer (architectural overviews and the like) but the bulk of work will remain the creation of reference information about our product and its capabilities.

We are still tweaking things, and will continue to do so into the New Year, but the very fact that we’ve started to adopt this approach is half the battle.

The war, of course, continues!

We are nearing the end of a release cycle and will soon be starting the next set of workstreams and, excitingly, we’ve managed to push the involvement of the technical writers right up to the early design stages.

What does this mean?

Roughly speaking the process of creating the stories is one part of the scoping and planning stages of our development cycle. Each feature is broken down into a set of requirements, and those requirements are further broken down into one or more stories. The stories are then broken down into discrete work tasks (a few days work at maximum).

The stories are stated in terms of “the user would like to … ” and are used to help the developers understand what they need to do to meet the requirements. We are hoping that, by writing them, we can both be involved in the early design stages as well as gaining an early start on the product documentation. The stories will become the concepts for the documentation, and we can then flesh out the tasks and reference information as and when the development work is completed.

Be interesting to see how well it works, but hey it’s worth a try.

Attending a conference is a mixed bag of experiences yet regardless of your knowledge in certain areas it is always a worthwhile to meet up with your peers and discuss the various common issues, gripes, moans and solutions that we all share.

I was also lucky enough to bump into some ex-colleagues and to meet some email correspondents face to face, not to mention the numerous interesting conversations I had with other delegates. Yes it’s safe to say that the value of connecting with your peers is high and entirely justified the cost of the conference.

That aside there were also a couple of subtle themes that emerged during the sessions, the main one being that to enable us to work smarter, we need to push our involvement as far upstream as possible. Joe Welinske hinted at this as a way to make sure we are working on the highest priority items, and this view was further (obviously) expounded by user experience expert Leisa Reichelt. Considering that many of the technical communication questions and considerations that crop up are frequently answered by the stock response of “know your audience”, it was a timely reminder that by pushing ourselves towards the point where we can gather product influencing information about our audience we can start to make better decisions both about WHAT to write and HOW to write it.

Other thoughts, on a random basis:

• Can we provide our online help in a single session browser (using something like Adobe AIR?).
• Can we leverage the Web 2.0 ideas of commenting and voting on help topics?
• Content is THE most important thing (sometimes it’s good to be reminded of this basic fact).
• Choosing our single source solution quickly was the right thing to do, they all have flaws so we will find them and get round them sooner rather than later.
• Can we look to web CMS to help provide a better set of technical information?
• The first page the user lands on is crucial, break from the traditional model and create custom landing pages containing anything and everything that helps get them back on task.
• Is the (stereotypical) persona of a technical writer actually stacked against driving change? Is that why so many of us are stuck following best practice? (I’m presuming best practice here to be a bad thing.
• Jakob Nielsen was quoted 4 times by different speakers – do we really need any more evidence that we need to be user experience/usability minded when writing and structuring information?
• If possible, define a variety of contexts within which the information can appear (version, product, country, etc) and use initial custom searches to provide a sensible landing page.
• There are MANY lessons to be learned from websites, most of which have Information Architects and UX Designers, something we don’t typically have access to.
• Users don’t care what kind of information they get as long as it answers their question.

Overall it was an excellent conference, and it was great to hear some of the things I’ve seen discussed in various blogs being brought to a larger audience. Definitely one to attend next year.

—

I’m not the only one that enjoyed the conference, Ellis rounds up his thoughts over at the Cherryleaf Blog.

Notes and thoughts from Day 2 of the User Assistance Conference

Session 1 – Juliette Fleming – XML Tagging and Search Facets
An early start for an interesting session in which Juliette outlined how Oracle have introduced search Facets to their online help system. Essentially a facet is a tagged chunk of information or help topic, and their help system has been coded to make the most of these by using the tags to decide in which context the help topic should be used.

This allows their help system to display information, for example, for a given product version, language, product and topic type when the user clicks to get help from the application. The facets are also used to present, essentially, pre-populated searches as a starting point (or Keystone Concept, perhaps) for the context-sensitive help. A smart idea.

Session 2 – Tony Self – Implementing Collaborative Authoring with Wikis
I didn’t attend this session but heard it was a good introduction to the topic for beginners. Having presented on this topic myself I figured it was safe to take some time out.

Session 3 – Rachel Potts and Brian Harris – Delivering Help in a Support Portal
An entertaining presentation on a topic that matches some of my thoughts of where my team and I should be heading. The core problem that Red Gate had was to tie together the myriad of information sources into a cohesive whole as they figured that their users didn’t care where or how they got the information they needed, even though Red Gate offered many distinct to try and guide them to a particular type of information.

With a little effort they came up with a solution which included restyling some of the existing information, and taking a new direction for the online help, recognising that most of their users would look for Support rather than Help (acknowledging that most people don’t like to admit they need ‘help’!). Shifting to Author-it for their technical writing team, they post-process the output to provide better metadata which enables the search engine and supporting presentation framework components to offer the best information at the best time.

As we are moving to Author-it it was very interesting but I was a little disappointed to find out (when chatting to Rachel and Brian later on) that they are ditching Author-it because, when creating new versions of topics, you lose the associated metadata. I’m hoping that’s just a bug that has yet to be fixed and will be checking that with Author-it very soon.

Session 3 – Dave Gash – Introduction to XSL Transforms
Following on from his presentation the day before, Dave suggested that this would be an easy to follow session on a fairly simple topic (even though it can end up being very complex to pull together).

However, having dabbled with XSLT myself I decided to sit this one out and spent some time chatting to some of the vendors.

Session 4 – Leisa Reichelt – Practical User Research
Having been an avid reader of disambiguity.com, where Leisa blogs on User Experience topics, and as it wasn’t directly a technical writing focussed presentation, I was looking forward to this presentation. Leisa’s style and delivery kept it interesting and informative, and seemed to be very well received.

Taking the role as a user advocate is a common one for a technical writer, and a lot of what Leisa was discussing was simply taking that a step further. She offered some suggestions on how to capture better user information as well as offering some simple reasoning that shows you can do useful research with a small set of subjects, and a simple model that shows that, without all the correct design processes in place “changing buttons on a user interface is like shuffling chairs on the titanic”.

As I’ve mentioned here on this blog, I’m a big fan of technical writers pushing (or encroaching?) into other areas. For many smaller companies without the budget to hire a dedicated usability professional it’s good to know that even a small effort in this area can make a difference, and that effort will mean a better understanding of your audience which is always a good thing.

Session 5 – Matthew Ellison – Creating Table Styles in CSS
Again, another session I skipped largely because I’m quite comfortable styling with CSS and a quick google suggests similar information is widely available online.

Session 6 – Prof. Geoffrey K Pullum – Far from the Madding Gerund
I have to admit that it was with a wary head that I took my seat for the closing session of the conference. I’ll happily admit (and lord knows there is plenty of proof right here in this blog) that whilst my writing is acceptable the finer points of grammar are occasionally ignored, so the thought of listening to a grammarian waffle on about deontic modality or ditransitive verbs didn’t exactly thrill me.

So it was with some humility and shame that I apologies to Professor Pullum as his talk was fascinating, funny and hugely enjoyable. Seating his advice in examples, and several quotes from The Importance of Being Earnest, he assured as all that our writing was perfectly acceptable and that we should ignore people who seek to enforce arcane and just plain wrong grammar rules. Split your infinitives if you must, dangling your modifiers and feel free to end that sentence with a preposition if you feel the sentence warrants it.

Ultimately, Prof. Pullum assured us, we are all professionals and the way we write is accurate for the audience. That and the fact that a lot of grammatical advice is complete nonsense.

If you get the chance to hear him speak, do so. Even if only to hear his range of accents, all of which are executed so well I have to wonder if he spends some time practising them.