Month: May 2008

bookmark_borderRecently Read

Posted on

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.

bookmark_borderDITA Maturity Model

Posted on

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.

bookmark_borderHealth update

Posted on

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.

Phew.

bookmark_borderIndiana Jones and the sunny weekend

Posted on

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.

bookmark_borderDo online communities work?

Posted on

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)

bookmark_borderGetting old?

Posted on

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!