Recently Read

I’m utterly failing in my attempt to make this a weekly feature on this site. Maybe I should cut it down a little, thoughts and comments are appreciated. Writing an Interface Style Guide Some handy tips for what to include in any user interface guidelines document: Interface style guides are extremely useful to define best practices for design and development. However, keeping that information updated and functional is imperative. A glossary, an index, references, acknowledgments, etc., are among some of the supplementary details you can add to make the style guide as helpful as possible. A Climate of Fear among Technical Communicators? Prompted by a panel in the recent STC Summit, Ben Minson outlines some basic tenets of employment which, …

Continue reading

Recently Read

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 …

Continue reading

DITA Maturity Model

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 …

Continue reading

Only the good die young

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 …

Continue reading

Recently Read

Blimey, another week has flown past and, as ever a few things have caught my eye. 9 ways to gather user feedback It’s often a struggle to get true user feedback on your documentation, Craig Haiss offers some suggestions to improve things in this area. Whilst I’ve tried some of these, and had heard of them all, it’s worth a look to jog the memory: You can write the most detailed instructions in the world, but if they aren’t the instructions users actually want, you’re wasting your time. That said, how do you go about gathering feedback to flesh out your documentation? Tech Comm Job to Job Title: Something Lost in Transit? Ben Minson is musing on job titles and, …

Continue reading

Recently Read

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, …

Continue reading

Back to DITA?

I’ve mentioned DITA a few times on this blog, and my DITA is not the answer post is still attracting attention. As I’ve said, I think the DITA standard is an excellent one for software documentation and the DITA movement is slowly catching up to the hype. I’ve never given up on DITA and had always planned to use it as the basis for the next stage of our content development, and as it happens the switch to a full DITA/CMS based solution may be closer than I had anticipated. We have been considering how best to publish up to date information in keeping with patches and minor releases, and if we can tidy up and publish useful information from …

Continue reading

Recently Read

Having been ill for a couple of weeks I’m just catching up with my reading list and there have been some fascinating posts and articles to read. Quite a few of them struck a chord and I’ll need to give them some more thought before I tackle them myself but all in all it’s a pleasure to be able to read such insightful posts from some very smart people. Ain’t blogs wonderful. The agile technical writer An excellent write up of the typical processes followed by a technical writing team in an Agile environment. It’s good to read this kind of thing, as it matches roughly what we do so… we must be doing it right? In a similar vein …

Continue reading

Why AuthorIT?

As I mentioned before, we are planning to migrate content from FrameMaker to AuthorIT, staging the migration across two different product sets (and no small amount of time!). I’m in the process of evaluating AuthorIT for, despite having used it before, it has recently been overhauled with a spiffy new UI and some new features. AuthorIT is a single source system, with content stored in a central database, which can publish to most (all?) of the formats that anyone would ever need. It includes an editor, supports multiple users, and has some additional add-ons for localisation and so on. Their website is very good if you want more information on their product. After downloading and installing the trial version, which …

Continue reading

What’s in store for 2008?

Back after a couple of weeks of merriment, over-eating and general lazing about. Hopefully the festive season was as good to you as it was to me. But enough looking back, this time of year is all about looking forward. So what is coming up in the next 12 months? Well, I’m hoping to start migrating some content from Structured FrameMaker to AuthorIT, having decided that the overheads required to get DITA up and running just don’t stack up against the cost of ownership of AuthorIT. I’m a big fan of the principles behind DITA, and I will keep up-to-speed with progress, but it doesn’t suit our needs here. I’m also hoping to post a bit more often here, and …

Continue reading