Tag: DITA

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_borderOnly the good die young

Posted on

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.

bookmark_borderRecently Read

Posted on

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?

bookmark_borderRecently Read

Posted on

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.

bookmark_borderBack to DITA?

Posted on

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 our internal Wikis and support system. The nature of the product we work with means there are a lot of different usage patterns, not all of which we would document as they fall outwith typical (common) usage.

So, how to publish formal product documentation, in-line with three versions of the product, in PDF for ‘printed’ manuals, JavaHelp to be added to our product, and HTML to be published to a live website alongside other technical content (ideally maintained in the same system as the product documentation). Storing the content as XML chunks also allows us to further re-use the content programmatically (which can be tied into our product in a smarter, dynamic, fashion).

The obvious answer is single source using DITA to structure the content, storing the content as XML to give us the greatest potential avenues for re-use. Nothing particularly startling there I know, but it’s a switch from the direction we had been considering. So I’ve been catching up on what’s new in DITA-land and have to admit I’m a little disappointed.

We already have FrameMaker and Webworks in-house, although both are a couple of versions old, and thinking we might keep using those applications I’ve been hunting about to see if I can find a solution that offers a coherent, end-to-end, story. There are several CMS solutions which require an editor, editing solutions which require a CMS, and a few products that straddle both CMS and editing but then require publishing engines.

I understand that it would take a collaboration between vendors to be able to offer a simple, seamless solution

In addition to that there does seem to be a tendency for any DITA focused solution to remain the remit of the overly technical. Don’t get me wrong, I’m quite happy delving into XML code, hacking elements, or running command line scripts to get things done. But surely I shouldn’t have to resort such things? Now, I’m sure there are many vendors who will tell me that I don’t need to worry, but I’ve seen several demos and all of them miss a part of the FULL story.

Come on then vendors, stick your necks out. If you are a CMS provider, then recommend an editor. If you sell editing software then talk nice to a CMS vendor and start promoting each other (yeah Adobe, I’m looking at you!).

And yes, I’ll happily admit that maybe I’m just not looking closely enough. If only there was some sort of technical community website that I could join, perhaps with a group or two on DITA? That’d be great.

Ohhh wait. There is! (not the most subtle plug in the world, was it? I think the new Content Wrangler communities could be a big hit, do check them out).

Have a got the wrong end of the stick, are there really gaps in the market in this area at present or is it just my imagination? I guess I’ll be running a fair few evaluations over the coming few weeks and, of course, I’ll post my thoughts and findings here.

bookmark_borderRecently Read

Posted on

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 I’ve recently written up an article for the ISTC Communicator magazine which outlines what I consider an average day in my working life. Naturally there is no such thing but the things I do, and the processes I follow match Sarah’s.

Interesting quote from Matt Haughey

My ideal blog engine company would hire some seasoned blogger and technical writer to be a documentation czar, keeping docs up to date when new versions are launched, produce screencasts for introductory users, and provide complete documentation at a stable URL that applies to every version of the product.

Moving legacy documentation to DITA
Scott pointed out this interview with Joann Hackos and, as ever, she offers sensible advice, particularly as I’m in the midst of planning such a move (to AuthorIT, not DITA):

Among your previously existing information, some of it we may call legacy because it documents products that are not changing much. Much of this information isn’t worth changing. There’s low value in converting or updating it.

The History of Visual Communication

Visual communication is the communication of ideas through the visual display of information. Primarily associated with two dimensional images, it includes: art, signs, photography, typography, drawing fundamentals, colour and electronic resources.

I’ve not read more than a couple of pages but this is fascinating and worth a look if you are at all interested in information design of any type.

Developing documentation, the FLOSS way.
Found on the DMN blog, this looks at the creation processes for documenting Open Source Software:

The common challenge is to create useful FLOSS documentation in a timely manner. The documentation must be continually updated as the software and projects evolve. It must be simple to understand yet comprehensive. The documentation must be easily translated into dozens of languages. It must be easily revised and distributed in a variety of display and publishing formats (HTML, PDF, PostScript, etc.).

Some handy tips and thinking points for anyone looking to streamline (and speed up) their content creation processes.

Writing in times of resource constraints
Mike Hughes offers some sage advice with some business perspective applied to the resourcing issue many of us face:

If your resources are tight, ask yourself whether you are writing the essential stuff at a level of quality users will notice

“Good enough” documentation is a reality that many of us don’t like to admit, but there are good reasons to understand when it is applicable to use that benchmark.