A quick note this week: If you know of any blogs out there that focus on hardware documentation writing I’d love to hear about them. I’m keen to see if there are other topics being covered out there as I’m aware that my scope is defined by my current interests. Right, let’s press on.

Can online help show “read wear?”
Anne Gentle ponders on how best to show the online help topics which have the most traffic, and comes up with some interesting ideas:

“You could … show the most searched-for terms when the user searches. Concepts may be more easily connected when you understand what others were searching for.”

To my mind anything that helps people find what they are looking for is a good thing, and these more subtle, dynamic, pathways are a tangible advantage to delivering content online.

Do We Really Need Structured Document Formats? (Is Real Reuse Possible?)
Eric Armstrong investigates the many and varied aspects of structured authoring, and offers a balanced view of the pros and cons from his own point of view:

“I know from personal experience that it is possible to be “seduced by the capacity for reuse”, to the point that you over-engineer your docs like crazy, and take forever to deliver something “perfect” that would have much better received had it been much more imperfect, and much more rapidly produced!”

Can better technical documentation give your business a competitive advantage?

…technical documents - the user guides and help systems used regularly by customers - at the centre of the corporation-customer relationship, and calls such documents “value generators” as they help build trust and confidence.

Striving for Success in DITA Conversion - A Quick Reference
From Noz Urbina, some sage advice that I’m filing away under “Obvious but worth being reminded of”:

A lot of people see ‘project scoping’ as overhead that delays ‘production’, but it’s a classic example of ‘measure twice, cut once’.

A bit short and sweet this week, such is the price for a four day week though.

I mentioned this in passing last week but having had a little time to delve into the model in a little more depth I thought it was worth re-visiting.

The DITA Maturity Model as an organic model that is still being developed. Rather smartly it’s presented in Wiki format allowing anyone who is interested to comment and debate any and all of the content.

The model itself follows a familiar pattern with six levels of maturity against which you can map where you and your organisation sit. However the DITA Maturity Model starts with the presumption that you are already committed to topic-based writing, and I think that’s a gap that needs to be addressed.

For me, the model allows me to explain to my boss (and his boss) why investing in DITA as a document schema is worthwhile but it misses the gap of why we should change what we are doing at all. Once you have made the leap, the maturity model is all well and good but MAKING the leap in the first place, well that can be considerably harder.

Of course I’m not the only person who realises this, and in steps the DITA Wiki which has an entire section on building the business case for DITA.

The DITA Wiki is interesting. Not only is it chock full of useful information but ALL the major players in the single source/content reuse arena contribute to the content and discussions. Again it’s telling that it grew up alongside the growth of DITA usage.

Anyway, the DITA Maturity Model is definitely worth a look if you are considering heading down the DITA road. If nothing else it will give you a better understanding of the road ahead, some of the pitfalls you will encounter and the benefits you will gain.

Since the turn of the year I’ve been thinking a lot about online communities and let me just say, right here and now, they are bloody hard to get your head around. I’m pulling together a developer community website for my company, with technical information and knowledge sharing being the core aims. It’ll be used by customers, partners and our own internal staff (fingers crossed!).

The simplest part to digest is the technological aspects, as you can map your requirements directly and let that drive your choice of tool. You can make decisions based on feedback from prospective users and ultimately most tools can be made to do what you want (ohh didn’t I say, this is utopia where you get all the resources and time you need… ahem).

Content is another thing to consider, with both the creation and manipulation of content key to making sure your new website thrives. I’m planning ahead and hope to have a few articles that can be published at a regular rate and then see where it goes after that. I’m certainly hoping that it won’t solely be a push driven website.

Audience next, and luckily for me I’ve a fairly good idea of the scope of the audience. They’ll be technically minded, as it’s a developer community, and I’m going to be playing on that as much as I can. From the SUPA event I attended a few weeks back - - “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 becomes a little harder to predict what the community will want from a website. I’m happy to adapt plans and add new features if required but I need to make sure that, from the outset, there is enough ’stuff’ to attract repeat visits to the website.

And this is the point where my train of thought leaps the rails as I veer from how to manage the new content (where is it created and stored? WHO creates it? who OWNS it?), how to manage the current/legacy content, how to enable the community, how to sustain activity, how to tie the website into our corporate presence, how to creates paths of information and support informal learning, how to allow sharing of ideas with a level of control (or none?) and on and on. It’s a very long list that grows every time I look at it.

Thankfully there are many good examples of online communities that work. However the one disadvantage we have is that the bulk of our audience (our own staff) already have resources they use for this type of interaction - internal mailing lists - and shifting them to the developer community will be a challenge.

Further reading:
The architecture of participation
Here comes everybody
Clay Shirky talks about his book, Here Comes Everybody (vid)
Interview: User participation and social networking (MP3)

Another grab bag of, hopefully, interesting posts, it’s a varied bunch this week which fits with my current mindset which is grabbing at a large variety of different topics and trying to make sense of them all (and I think it’s finally beginning to come together). Enough of that, on with the links!

Do you write FAQs? How about NAQs?
As Kevin Kelly points out, we’ve all read FAQs which aren’t, instead they are NAQs - Never Asked Questions, “Easily answered questions that no one has ever asked.” He then goes on to make an excellent point, namely that:

…if you don’t answer the FAQs, the internet tubes will. That’s what forums are. Customers, both potential and present, bring their real questions to find real answers. Here people who don’t work for the company will supply answers. Often these answers are good, but often the organization could supply a better answer, if it were really running a FAQ. Why not make it easy for everyone to find the best answer — from the organization’s point of view?

A Quarky new approach?
I mentioned Quark’s new Dynamic Publishing product when it was announced, and after initially being a little excited (”dynamic!” “publishing!”) I became a little confused by what it was actually going to offer.
Sarah at the Palimpset blog took an in-depth look and found that it was really just a form of single source, and suggests that:

if the “dynamic publishing” bit in the name is a preview of coming attractions rather than an accurate label for what they have now, then perhaps there’s hope. But I’m glad I’m not the one trying to pull this off because from out here, it looks like an extreme long shot.

The post is an excellent investigation of what drove Quark down this route.

Information Design Patterns
WARNING: Site requires Flash and is heavy on bandwidth.
If you ever have to create an infographic (a graph or other type of formal diagram) then have a look at this website for some inspiration and ideas for the future, as well as some in-depth analysis of the form factors presented.

Top 8 mistakes in usability
Given that we have recently revisited the idea of using personas and have spent some time trying to guess what they should be point 2 hit home. I know, I know, nothing replaces research based on REAL users.

Let’s pretend our user’s name is Jane. Let’s pretend she is 38 years old, drives a purple Prius, reads mystery novels, loves bulldogs, and likes to go sailing. Let’s pretend she comes to our website and likes feature A but not feature B. Therefore, we should develop more things like feature A. See? We’re very customer-centered.

This is the fun of creating a persona, which allows teams to make decisions based on fictional people, rather than doing the hard work of listening to real customers.

We actually decided to focus more on user roles first, before broaching the subject of Personas, and I’ll be doing my damnedst to make sure we don’t run into these mistakes.

Trends, tools, technologies in online documentation
Sarah Maddox wrote up some great notes from the recent Australasian Online Documentation and Content Conference, including these from the session by Joe Welinske which was based on the results of the WritersUA Skills and Technologies Survey. Some interesting observations on Vista, trends in our profession and some things that we should all have on our radar, including:

Structured authoring — affects a growing number of technical writers. Joe sees this as the most important concept for us to learn about. It affects our roles and production process. The author works in a form-based environment, putting the content into pre-determined pigeonholes. Presentation is separate and automated.

I quite like the fact that this isn’t stated as single source which has other connotations. Perhaps more of us are closer to structured authoring than we think? I mean, we all use templates and predefined formats, don’t we?

That’s it for now, time to get ready for the bank holiday weekend here!

One of the reasons DITA has gained so much traction in such a short space of time is that the people behind it are taking advantage of the internet to publicise and drive it forward. With that in mind it’s great to see them open the new DITA Maturity Model out to the community:

This community is designed to bring the DITA Maturity Model to life, applying the “Wisdom of the Crowds” to the evolution and refinement of this approach to DITA adoption. The premise is that none of us is as good as all of us. The DITA MMC is an evolving resource that will grow and change over time with your active participation and contributions.

Definitely a good usage of the social media tools available at the moment.

One thing that struck me, taken from the Content Wrangler coverage, is a simple reason as to why more people are considering a move towards DITA-based content:

Enterprises looking to fast track their content strategy and minimize the risks of a big-bang initiative are choosing DITA–one of the most popular information models to suit today’s content–rich, multi-channel environment.

For some reason I hadn’t quite figured that out, but if you are putting together a business case built around DITA then it’s worth investigating this in more depth. That said, this is definitely one of those “so obvious I hadn’t considered it” moments!

The maturity model also highlights one of the reasons that DITA is proving popular even if it isn’t the best standard to be using for every circumstance. Quite simply, it’s because it’s young, new and (this is the important bit) is being developed in plain view of everyone on the internet. Admittedly I’ve not gone looking for DocBook or SD1000 resources but as they are already fairly mature they seem to be struggling to keep up with the pace of development around DITA. If DITA is the cool kid on the block, DocBook is definitely the wise old sage, stooped on the corner.

Social media on the internet thrives on participation and with DITA still growing up everyone has a chance to get involved and influence things, and that helps generate buy-in, which drives more improvements, which increases community buy-in… and so on.

So, even if you aren’t interested in DITA but are interested in how social media (online communities, web 2.0, whatever you want to call it) might help you and your company, it might be worth while checking out the maturity model and see if the same … erm… model.. can be applied to what you do.

So I’ve updated my bookshelf with a couple of new books, and an old one.

I’ve started The World Is Flat which is utterly fascinating, even if it is slightly outside of the more traditional technical communications area. However anyone with any interest in social media (aka Web 2.0) should give it a look. My personal opinion is that our jobs are going to become increasingly influenced by such things so it’s good to get a bit of perspective on how they are already making an impact.

Conference season is underway, with DocTrain and AODC recently finishing. As such there is a lot of great and interesting blog posts out there, some are catchup style so if, like me, you didn’t attend you can still get some nuggets of information from them. But the type I prefer are the ones which collate the various ideas and pull them together.

So, with that in mind, if you only read one of the posts linked below, make it the first one.

DocTrain Conference thoughts
Tom chats to Noz Urbina from Mekon and starts to pull together some of the varied threads I’ve covered here into a vision of the future which, in my opinion, makes sense. It’s great to see this kind of thing being discussed and it’s the step beyond where I’d gotten with my thinking. Well worth a read.

Some thoughts on writing better error messages
Real-world tales of woe shed some light.

This lack of coordination between error reporting and error origin often leads to incorrect human reasoning about root causes. One simple help to sysadmins (and other users) would be to report errors in context.

Separating content, structure, format and behaviour
One from a session of AODC which helps properly define how and why we should be separating out the various components of information production.

What we’re aiming for:
* Maintainability — you can change one of the above four components without breaking the others.
* Re-usability — you can re-use the same bit of JavaScript, for example, in other documents.
* Separation of skill sets — different people can work on the component they know best and enjoy most.
* Simplified updating of content — content is likely to be the component you update most often.

Designing for the Social Web: The Usage Lifecycle
Pertinent to anyone working with an application that has any form of social web (web 2.0, community interaction, pick a term) features, or for those of us trying to build an online community around their product

The lifecycle is particularly relevant to web-based software because the product is inextricable from the service. The product is the service. If a person has a question about what your software does, for example, you can literally build that answer into the software itself.

Wiki on a Stick
And finally, a downloadable, zero install, personal Wiki. May be useful if you want an example of how Wikis work. Extra handy for maintaining your own To Do lists or as a way to centralise your notes (or both).

That’s all for now.