Tag: <span>DITA</span>

Recently Scott Abel posted a heartfelt plea to get people all psyched up about how to better promote DITA to the rest of the world. He backs the idea of the DITA Adoption Technical Committee, stating that:

“we need excellent communicators with the gumption, know-how, and network to get the word out about the many ways DITA impacts the world and those who live in it.”

I’m a fan of DITA and as I read his post I could feel myself getting quite excited, he makes some excellent points about finding real world examples of the benefit DITA can bring but something just doesn’t quite fit. It’s taken me a while to get my head around this but, isn’t a standard supposed to be a technical implementation detail, not the main focus of life changing events? Ahhh but wait, Scott agrees:

“DITA cannot be the focus of DITA adoption and publicity efforts.”

OK, so we can’t focus on DITA itself and, as Scott rightly points out, the software vendors will soon turn discussions away from DITA and towards their own feature set, so we can’t look there for an example either. In fact it’s not until the latter half of the post that Scott really hits on what he would like us to do, and in my opinion the following sentence is the key to his entire argument:

“Let’s strip away all the noise that prevents normal humans from understanding what we technology addicts find so wonderful about DITA, XML, content reuse, content management, dynamic content, personalization, and so on. … The focus has to be on the human impact. How does DITA help make the world a better place? How does it make it possible for humans to interact with one another? How will it help everyday humans in their everyday lives? How can it help governments better serve their citizens?”

Big questions.

Whilst Scott is aiming at a top-down view of the world, there are lessons there for those of us who are trying to push these things upwards. Selling DITA as the fundamental part of a single source solution now seems a little odd, particularly when most business cases are focussed on ROI and the whys and wherefores surrounding the choice of tooling, so if you can detach the tool from the business case, and focus thinking on the benefits of DITA (rendering the tooling generic rather than specialised) you can start to really crack the story behind how adopting DITA as a content standard will benefit the customers of your company, THEN you have a much more powerful argument.

So, if anyone has any answers to those big questions, do let me know…

Work

Comments closed

A quick welcome to anyone visiting from the ISTC Communicator magazine. I feel a little spoiled getting two mentions in subsequent pages (10 & 12 if you are wondering) but I’m not really complaining.

Over the past year or so I’ve definitely got the feeling that the ISTC is changing, and it certainly feels like a more modern and dynamic organisation than it has seemed to be in the past. Perhaps that’s natural, but it’s amazing how little things like a redesign magazine and newsletter, and hopefully a new design for the website, can refocus the energies of those involved.

Anyway, thanks for dropping by, there are plenty of links and opinions to be found in the archives (scroll down a bit, they are on the right), and here are a few of the more popular posts:

Or perhaps you just want to download the RSS feeds.

Work

Comments closed

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, whilst we all know them, bear being repeated:

I think protection lies in being inventive. If management and your peers see that you go beyond the bare minimum and the mediocre because you’re interested in what you’re doing, they’ll see value. If you invent in order to solve problems and to benefit your team and the organization, they’ll see value.

Interestingly, this aspect of professional life raises some issues, some of which were encountered by Anne Gentle at the STC 2008 Summit.

STC2008 – Wrap up STC Summit trip report
Anne heard a couple of similar issues during the summit (as well as a lot of other great stuff), but she noted that:

proving that [an] idea needs to be implemented in the first place means understanding how to convince management of the value.

It seems to be something we all struggle with, providing ROI to back up our reasoning behind choices of tool and technology. Which brings me neatly to the next post…

What is the Best Metric to Measure the Success of Your Reuse of DITA Topics?
Of course you’ll have to have provided enough evidence to at least get a pilot project or proof of concept off the ground, but if you have, how do you get the most from the data you are capturing. Bill Hackos suggests you should measure the percentage of repository words that are reused in context:

The ratio of the repository content to the produced content metric works at the content level rather than at the topic level. This metric is proportional to actual costs because translation is charged by the word, and maintenance costs are proportional to the volume of content rather than to the number of topics.

I’m not a huge fan of such quantitative measures but sometimes needs must. The article mentions some other possible metrics, and if you are considering a single source rollout give it a look as it will spark some thoughts I’m sure.

Finally a couple of quick links that do exactly what they say on the tin:

Blogging

Comments closed

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.

Blogging

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.

Work

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.

Work

Comments closed

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, as well as raising a giggle, ends up stuck. Job titles, as a way to convey what you do for a living, are important.

… the dictionary says one who documents is a “documentalist”—however, I’m reluctant to adopt a job title that includes the word “mental.” So this is where you get “documentation specialist.” The same goes for “usability specialist.”

It seems a little funny that, being writers at heart and therefore professional manipulators of language, some of the terms we pick for our field don’t easily translate into job titles.

I’m currently experimenting with the title “Technical Information Manager” which is a little OTT but seems to fit my current role, thankfully my company, like myself, isn’t hung up on formal job titles (they prefer that you, you know, get on with whatever needs done). So, what’s your job title?

Typography humour

Glossary of DITA terms
Bob Doyle is wondering if there should be a central, user-maintained, glossary of DITA terminology:

many DITA-related terms are not defined … They are simply assumed.
And some is insider jargon, like reltable for Relationship Table.
And there is no convenient alphabetical listing.
You can search for terms on the DITA Infocenter, but then you have to already know the term.

This got me thinking. If you have been toying with setting up a documentation Wiki, then this may be an excellent place to start. It might also throw up some interesting usage of terminology. Definitely something I’m going to have a stab at (well, I’ll add it to the list of things to try).

RoboHelp vs Flare
Interesting round up of posts and comments on this topic. If you use, or are planning to use, either product, give it a look.

And I’m done. Another week in the wonderful world of Technical Communications has gone, I wonder what next week will bring?

Blogging

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.

Blogging