The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert?

The question above was prompted by a presentation I attend last week, given by Paul Sherman on behalf of the Scottish Usability Professionals’ Association, entitled: THE PERPETUAL SUPER-NOVICE.

The basic premise is:

the tendency of people to stop learning about a digital product-whether it’s an operating system, desktop application, Web site, or hardware device.

A simple example: Someone who has learned that you can cut and paste text in Word by using the Edit menu options and the application doesn’t support them learning how to do the same thing in a more efficient manner.

Many applications (and the documentation that supports them) is aimed at either getting from beginner to novice level, or getting from some kind of mid-level up to expert. There is a huge gap in application design (and, again, the documentation that supports it) around helping users get the most from their usage of an application.

That mid-level area is what Paul refers to as the Super-Novice:

in the absence of extrinsic motivation, it seems that many people stay novices or, at most, become a form of knowledgeable novice that I call the super-novice. Super-novices know a lot about the limited parts of a system they use regularly and almost nothing about the other parts

Obviously the presentation was focussed on usability and application design, but it got me thinking about how documentation, or perhaps we should be calling it supporting information, suffers in the same way.

It’s fairly easy to get into the mindset of the beginner; presume the reader knows nothing and assume a level of learning in which to frame the information. Expert level information is a little trickier but could be stated as specialist, or niche, information.

But what of the super-novice? If we want people to get the most from our applications (and we do, don’t we?) how do we enable the super-novices and help them become experts?

Paul touched on some of the aspects of web 2.0 communities, and how providing “achievement motivation” is a key method for enabling learning and helping build the “need for mastery”. At this point it is easy to see that traditional documentation, printed manuals or online help, will fail the user in this aspect. It simply can’t respond to the differing needs of the audience.

Of course there is still a requirement for those carriers of static information, but to really enable your users you need to start thinking beyond a simple push of information.

Looking at the current crop of social media networks and communities, it’s easy to pick out some common themes; there is always a core group of users who will soon become forum experts, reliable and helpful members of the group. These are the experts and the challenge is to help everyone else get to their level.

I’m still not entirely sure HOW one goes about that, but it’s clear that if this is an issue you can identify with, and that your audience acknowledges, then you need to start looking around for some new models of learning. The internet is full of them, just find a burgeoning online community and see how things work there and try and match it to your own audience.

The times they are a’changing, and those gaps in your documentation will only get bigger and soon, alongside the application, you may start to lose your audience. We need to consider those gaps, the line between A and B, and figure out how to help our users traverse it safely.

—-

Paul writes on usability issues (and more) on his blog, and for UX Matters where the origin of the presentation can be found (and from which the quotes in the post were taken).

Been a while since I did one of these and, as ever, they reflect some of the things that have caught my eye over the past week or so. A couple of things on DITA which have me rethinking my approach towards it, and a some links to posts discussing … welll community, social media, Web 2.0 kind of stuff, some of it is a little away from my world but it’s good to get a different point of view on these things.

Docbook versus DITA
Not the first comparison I’ve seen but an excellent summary comparison of DocBook versus DITA. Whilst it was written by someone who admits that they were looking to portray a favourable outcome for DocBook, it’s an well-balanced set of information and will be useful to many.

From Free to Three ($100K)
One of the issues I have with DITA is the cost associated with implementing a complete end to end solution, something that, apparently, I’ve been mistaken about:

Our DITA Tools from A to Z section on the DITA Users website lists every software and service up to those $300,000 publishing solutions. But our policy of free member access to online tools means that anyone anywhere in the world can at least get started (our membership fees range from free to $100 a year).

We call our approach “DITA from A to B,” authoring to building and, of course, publishing structured content.

Definitely something I’ll be checking out.

Agile Content Development

Social media represents such a fantastic opportunity because it allows us to create and launch media properties directly to the public. But even more of a blessing is the direct and indirect feedback process that naturally happens in this space.

You put something out there, and the crowd will reveal the direction you should go. It’s not necessarily always the wisdom of the crowd, but rather the desires and objections of the crowd that guide you.

Use of social media needs fear

What about all of the fears of potential liabilities, losing control, and (the night terror) negative comments? IRRELEVANT! All are either uncontrollable (and were all along) or can be mitigated with good policies, procedures and education. Social media carries as much risk as email. You should be more afraid of losing the battle for relevance.

Is IT in danger of becoming extinct?
I’m not entirely convinced but, once again, this post suggests that there is a shift of balance, and that shift is entirely driven by users and their new found abilities to build communities around, or away from, your products.

Social media empowers users at the expense of IT. Enterprise 2.0 companies marginalize IT by putting powerful tools directly into the hands of non-technical workers, bypassing IT in the process.

I’ve been trying, unsuccessfully, to add a better (Google) search to this site. Alas because I have a hand-coded WordPress theme, and I last looked at it about a year ago, I’ve managed to bork the search results location.

So, for now, the search isn’t working. Nuts.

Thanks to Tom, it’s all working now, and it’s even better!

As featured in the Spring 2008 edition of Communicator, the magazine for ISTC members.

I’m the Publications Team Lead at Graham Technology, a mid-sized (and growing) software company based in Scotland and like many people in this field, I have a wide range of duties. As well as the more traditional technical authoring work, I also manage resources, consider strategy and working practices for the team, and generally do my best to represent the user during development meetings. I also find myself spending time considering the information strategy of the company, investigating translation requirements, and keeping up to speed with the Technical Communications industry.

I joined Graham Technology just over a year ago and it’s my first time working in an Agile software environment. The development team use the Extreme Programming (XP) methodology and it’s taken a little getting used to, particularly as all my previous experience comes from more traditional teams, with long timescales, project managers with Gantt sheets and lots of process documentation to be completed.

There are specific challenges to working in an Agile environment and to a fair extent they shape my working day and, whilst everyday is different, they all start with the same thing. Caffeine.

I’m usually one of the first people in the office and, once the coffee machine is going, I take advantage of the peace and quiet to pick through the emails that have accumulated overnight. I monitor a variety of automated emails from different systems, all of which help me build a coherent view of what is happening during a release cycle.

We have a development arm in Jakarta so I take the time to sift through their work to check for any possible impact on the documentation. Anything that catches my eye is noted on an index card and stuck up on a dedicated whiteboard allowing anyone to see what is outstanding at any given time.

Next up is a quick check of the Publications build to make sure it has run successfully during the night. We currently use Webworks to generate Javahelp which is automatically compiled into the product each night; small changes are quickly actioned and committed to the documentation, and are then available in the next software build, keeping us in-line with the principles of Agile development.

The final set of generated emails I check are from our bug tracking system and they list what has been fixed or added in the past day. Again, anything that may impact the documentation is noted on an index card and added to the whiteboard. And, by now, the coffee is usually ready; milk and one sugar, please.

Last but not least, there may be requests for information that have come in from our Deployment staff out on customer sites. Sometimes all they need is a copy of a specific manual, other times it takes a little research to find the information they need. Once that’s done, I spend a little time skimming my RSS feeds for anything else of interest.

It’s now around 9am and the office is filling up. I typically have a few things to chase up from the previous day, and it’s a good time to have a few quick chats with the developers before they get too embroiled in their daily work.

Our Development Group is split into six distinct teams, with three technical authors covering their output from brand new features to bug fixes and product enhancements. Most of the teams have a standup meeting every day to take a quick look through the tasks that need to be completed, and during these I play user advocate, considering UI design and any information requirements that need considered. It’s a very dynamic and collaborative way of working.

Working within an Agile development environment means that things move fast and information flies in from all sorts of sources and directions. Monitoring email, changes to our internal Wiki, and chatting to the developers and testers in the teams are all part of a typical day. Placing yourself in the path of these streams of information is the best way to keep up to speed, and learn what is really happening on a day-to-day basis.

I also try and keep in touch with Marketing and Training to understand their plans and see if there is any cross-over with what we are doing in Publications. I’m striving to make our message more consistent, and improve the way we plan, design, create and distribute our product information, and maintaining direct lines of communication is crucial.

Part of my Team Lead role is to make sure the product documentation is meeting customer expectations. We have two products, a user-friendly out-of-the-box product which our Deployment staff extend using our development kit. Gathering requirements from the Deployment staff is a constant push-pull exercise and, as they are talking directly to the users of our out-of-the-box product they act as proxies who can be interviewed to make sure we are providing the right information, at the right level for the expected user.

The rest of my time is spent writing documentation. This is broken into three main types of work at any one time; small changes to the products which require less than half a day to complete, larger changes to the products which may take between a day and a week to complete, and documenting the brand new features that are being added to the product.

I start with a high-level plan of what is required and then trickle the information into the relevant document throughout the development cycle, handling changes in scope and requirements as they arise. I try and plan to work on small chunks of content, making it much easier to drop something if the requirement is descoped at any point (this is a key reason we are moving to single source our content) and I spend any additional time researching and learning the part of the product I’m working on, playing with the software regularly to make sure I fully understand both how it works and how it would most likely be used.

Like everyone else, I don’t really have a typical day. I do try and stick to plan for the first few hours but interruptions, conversations and changes of priority are all part of the challenge of working in a fast-paced software development company.

I got home this evening to find the next issue of Communicator sitting on the mat. Thankfully it was in one piece so obviously the cat hadn’t found it…

Anyway, just to confirm that, yes, I am the same Gordon McLean who features in the final piece in the magazine. Worryingly that means you now know what I look like, so I can only hope it doesn’t put you off visiting my blog again in the future.

I’m also going to be featuring in the monthly newsletter, but more on that when it happens.

The article was a “day in the life” style piece and although re-reading it brought a few omissions to mind, it remains a fairly accurate portrayal of a typical working day. Truth be told I don’t actually have many days like that at the moment as we are nearing a release date but the main bones of the article are still valid.

For those that aren’t ISTC members (and why not?) I’ll be posting a copy of the article soon, meanwhile I’m off to read the rest of the magazine.

As we are in the midst of rethinking our publishing processes, I’ve been looking at the current crop of tools, and (for our needs) three of them stand out over their competitors. Adobe, AuthorIT and MadCap seem to be heading for a battle royale, with the latter two the David to Adobe’s Goliath. But who will win?

Before yesterday I wouldn’t really have put MadCap in that battle but it’s been a busy time for MadCap, who (yesterday):

..unveiled its roadmap for the first complete, native XML software family designed to solve all of a company’s documentation and authoring demands. The MadCap family will include five new products: MadCap Blaze, MadCap Press, MadCap Team Server, MadCap X-Edit, and MadCap X-Edit Express, as well as enhanced versions of MadCap Analyzer, MadCap Flare, MadCap Lingo and MadCap Mimic. The tightly integrated MadCap family will provide companies with an end-to-end solution for developing and delivering content in print, online and on the Web—and in their language of choice.

[full details]

OK, so MadCap have a lot of ideas, but what does this mean for the technical communications industry? Putting aside discussion on bespoke solutions, in what state is the current crop of “out of the box” products? And, ultimately, why is this news from MadCap so intriguing?

Looking at the current tools the obvious and dominating product is FrameMaker. Recently updated by Adobe and with a new lease of life alongside Robohelp in their Technical Communication Suite, the future looks bright for the product and as the market leader it’s a safe decision to adopt their products and, like Microsoft in the OS business, it’s safe to assume they aren’t going anywhere anytime soon. With a little work and additional tools, the Technical Communication Suite offers a smart multi-publishing system built around well-known and well-proven tools.

Then there is AuthorIT, which has been on my radar for sometime now, and the latest version certainly offers more functionality and builds on their core strengths. Their entire suite covers a lot of the areas that MadCap are targetting and it’s already being used by technical communications departments. The latest version is, in essence, a 1.0 so has a few rough edges and issues but the AuthorIT camp are making the right noises and I expect it to become a solid and viable solution for many people wanting to move into multi-format publishing from a single source.

At this point I should really mention the other tools that make up the rest of the market but as I’ve not really been heavily involved with anything else (Arbortext, ForeHelp, HDK are about it) it would be wrong of me to summarise both their market share and their futures (if anyone else has an opinion here I’d love to hear it in the comments). I would guess that, and I include AuthorIT and MadCap in this, the rest of the market outside of Adobe is fairly evenly split across a variety of products.

The new MadCap offerings bulk out their current product set into a complete end to end publishing system and, from what I can see with the limited details on offer, ticks all the boxes. On the other hand, both Adobe and AuthorIT will say the same thing so perhaps we need to see a little more detail before we get too carried away?

Yet, despite the fact that the feature set MadCap announced has a bigger overlap with AuthorIT, the feel is that MadCap are aiming squarely at Adobe. Of course, it’s understandable that they are aiming at the biggest target as chipping away at the other players probably isn’t a sustainable business plan, so the question is whether or not they can beat Adobe at their own game.

Given that Adobe were missing in action for a few years, the speed at which they have ‘caught up’ has impressed me but having seen demos of both their Technical Communication Suite, and of MadCaps offering (before these new products were announced) my gut feel is that Adobe have only caught up and aren’t moving forwards as fast as MadCap. In fact I think it’s safe to say that MadCap, and AuthorIT, are changing the game and I’m not sure if Adobe are properly positioned to respond.

As Ellis, over on the Cherryleaf Blog suggests:

I still have concerns that Adobe still really doesn’t understand the practicalities of technical communication, that features appear as solutions looking for problems to solve. However, Adobe is the market leader and, as we’ve seen in IT many times before, it’s often the company with the best marketing (rather than the best software) that wins.

The latest swathe of products gives MadCap a full, end to end, system that should be able to handle anything a ‘typical’ technical communications team can throw at it. In saying that, without a little more detail it may all be smoke and mirrors (something they’ve been accused of in the past) but the simple fact is that MadCap have already demonstrated they ‘get’ the current marketplace, and they’ve certainly made a big enough splash to warrant the attention.

I wonder, if we fast forward a couple of years, if the marketplace will still have one big player. I suspect not as the noises coming out of both the MadCap and AuthorIT camps speak of big things, so perhaps Adobe need to look over their shoulder and up their game? Regardless, the main winner of this competition is you and I, the technical writers who deal with these products on a daily basis. As far as I’m concerned, the biggest part of the MadCap press release is the fact it exists at all. Challenge the status quo and things start to happen, quickly, and the technical communications community can only benefit.

The boom of the internet is better documented elsewhere but the one key and founding principles is the ability to converse with anyone, anywhere in the globe. From the early days of IRC and email, onto graphical websites and instant messaging through to the current swathe of, for want of a better phrase, Web 2.0 services.

Twitter, blogs, social bookmarking, and online communities are the current rage but, do they work?

I’m a member of several email lists, swapping emails with a large number of people on a range of topics. I spend a fair amount of time filtering out topics which don’t interest me, and over time I’ve come to recognise various people by name. However email, whilst great for sharing information, is a limited when it comes to building communities.

Understanding who you are conversing with and the additional interests they have helps build trust, helps build better conversations and helps build communities. Transferring that kind of interaction online means we can better leverage shared experiences and hopefully make it easier to find other people with the same, unique, slice of knowledge and interests.

It’s only now, pulling together all the available technologies that such online communities are possible.

And the good news is that we, as technical communicators (content professionals) now have such a community.

Scott Abel, aka the Content Wrangler, has launched the Content Wrangler Community website and, having signed up and started using it a little I have to say that it is well worth a look. There are already several hundred members (825 at present), and these early adopters have started forming focussed groups, all of which relate back to our profession. In the words of the website:

Network with peers. Find jobs. Share information. Start a blog. Upload and watch videos. Join a group. Begin a discussion. Learn about software. Find events. Ask for help. It’s all here. Become a member. It’s free!

It’s safe to say that “social networks” aren’t everyone’s cup of tea, but I’d strongly urge you to check it out. Despite only having been launched a couple of weeks ago, it’s already proving popular and, as the conversations start and people start to find clever ways of using the various features available then it’s only going to get better and better.

Visit the Content Wrangler Community website today, sign up and join in!