Month: <span>May 2008</span>

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.


Comments closed

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.


Just a quick one as I’m back from the doctors where my blood pressure (after 4 weeks of increasing amounts of an ACE inhibitor) is now 144/86.

The upper number (systolic) is easily changed, run up a flight of stairs and it’ll rise. Sit still for 20 minutes and it will fall. The lower number (diatolic) is harder to change so that’s the one I was focusing on, so I was delighted to see it well below 100.

Considering the readings that started all this were 196/122 then it’s fair to say that the downward trend is favourable.


Personal Musings

Ahhhh what a nice Bank Holiday weekend that was.

Visited my Mum for lunch, then popped into to see my Gran for a while before heading home before the rush started (catching the end of the Scottish Cup Final). Saturday evening and we were out with friends for dinner and a screening of the latest Indiana Jones movie. I don’t want to spoil it for anyone, but suffice to say that having read several reviews I should’ve expected what I saw.

Yes, Harrison Ford is older but I thought he carried it well and the first 40 minutes or so skipped along just fine, with the usual romping, fighting, nonsense all in place. But after that it started going downhill. Fight scenes were obviously CGI’d, the plot got more and more ridiculous and next time I hear that George Lucas is writing a film script I’m going to track him down and shoot him (in his writing hand).

I was quite willing to suspend disbelief for this movie, give it the benefit of the doubt, and the first part of the movie helped me do that but it just got so bad towards the middle that I had no choice but to get dumped back to reality. THAT is the sign of a bad movie, one where I’m made painfully aware that I’m sitting in a cinema and my left buttock has gone numb. I’m quite glad I already own the first 3 Indiana Jones movies on DVD, I certainly won’t be adding this one to my collection!

Sunday found us in the garden, weeding and tidying up (mainly weeding), and yesterday we had my sister-in-law, a niece and a nephew over for a BBQ. It was a good day to do not much, a little prep, a little cooking and LOTS of food!

And best of all, the weather is back to grey nothingness today. Just in time for everyone going back to work.


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)


Comments closed

I’m one of the older people in our office. This is a new thing for me but I’m quite enjoying it. Don’t get me wrong I’m not surrounded by graduates but it’s fair to say that I’m part of the minority both age and experience wise.

And I’m loving it for the most part.

However the downside rears it’s head frequently, typically during a conversation about TV or music, or any other item that is now referred to as ‘pop culture’. Frankly I’m getting a little fed up of the blank looks and general bemusement that ensues whenever I start talking about things that happened only 10 years ago!!

Like most people who are older than 24, I still feel 24 (feel free to substitute your own “I’m not XX years old, I’m still 20-something” number) but I’m being made increasingly aware of the difference in age. I’m not overly bothered, in fact whilst I write this I realise that the only part of me that cares is that small bit of vanity that I try and avoid.

As for all that tosh about young people helping to keep you young, well perhaps it is true for those really OLD people, you know the ones over 40, but certainly not for a spring chicken like myself.

Hmmm, I seem to be undoing myself here.

Perhaps the word “old” is misleading. I’m certainly more mature and considered (sometimes), and have more experience so perhaps that is the key difference. If nothing else I’ve certainly learned from past mistakes so that has to count for something, right?

Age is a funny thing, particularly when you find yourself in a situation similar to mine where you are seen as “older” in the eyes of many, yet still consider yourself “younger” than others. A middle ground of middle-agedness which, I’m finding, isn’t as bad as it’s made out to be.

Roll on 35!

Personal Musings

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!


Faster Pussycat! Kill! Kill!
Is it wrong that I’d really rather Ollie killed the mice rather than bring them into the house to play? It’s one thing picking up a dead mouse, quite another to spend 20 minutes chasing a live one round the living room at 3 am.

Melody Gardot & R.E.M.
After catching her appearance on Jools Holland (and as a side pondering, does anyone refer to it as “Later… with Jools Holland”? No, it’s just “Jools Holland” innit) I listened to some samples from her album and promptly purchased it.

Listening to it I can picture her onstage persona, sultry jazz singer, and I wonder if that impacts how I engage with her music?

It was the same after I saw R.E.M. a couple of years ago, their last couple of albums had largely escaped my notice (to the point that, for example, I’m still not entirely sure on which album the track “Lotus” can be found), and I was a bit non-plussed… until I heard the tracks live.

Yet after the gig, re-listening to those same tracks now is a different experience.

Yeah I know, nothing startling but it’s been on my mind.

That and the fact that R.E.M.’s new album, Accelerate is rather stonkingly good.

Power out
All of a sudden the screen went blank, the music fell silent, and the power LEDs faded. We’d had a powercut.

“Bugger” he exclaimed in annoyance.

Actually he said “ohh fucksticks” because he was rather cheesed off having spent 30 minutes carefully crafting a newsletter entry. Then hope made an appearance for he had used Google Docs and Google Docs autosaves every now and then and maybe, just maybe, he hadn’t just lost all of his work.

And then the glimmer of hope widened, the websites he’d been using for research were opened in Firefox tabs, perhaps it will have saved them as well.

Lo and behold it was true. Google Docs HAD saved all of his changes, Firefox DID remember which tabs he had open.

Ahh the joy of the righteous, I KNEW I used web apps for a reason.

Mind you, it still amazes me that GOOGLE Docs don’t allow you to send the documents by email… I’m sure they have an email client as well… right?

Financial Ponderingmentness
Between oil prices rising, and the credit crunch … er… crunching, I’ve been taking stock of our financial situation. It’s not that bad, although the looming remortgage will impact it in one way or another.

I’m tempted to go through the remortgage process myself, following the Moneysavingexpert’s guide of course, but wondered if anyone else had done the same?

Cat Media Work