Tag: DITA

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

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 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.

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 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.

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 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.

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

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

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 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.

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 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.

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 limits your import and publishing but otherwise has all the features available for use, I fired it up and was greeted with the new interface. Based on the ribbons used in the latest version of Microsoft Office, it is quite a shift away from the previous version and it took me a while to get to grips with. However it is a huge improvement over the old version and once you are used to it, like anything, it’s very nice to use. Yes I know there are still issues being dealt with, but I didn’t run across that many during my testing, so I’m happy.

During my evaluation I spoke to their Business Development Manager who was very helpful in delving into some of the issues I had around versioning and set my mind at rest. I’ll outline how we are going to handle maintaining multiple versions of documents in another post, once I’ve given it a dry run or two.

One issue that cropped up was the location and format of the supporting database. You can run AuthorIT on a Jet database either locally or on a network drive although that is particularly performant, or run it on a SQL Server. As we are a small team I did consider the Jet database but our situation suggests a server database would be better. Which introduced another problem, price. SQL Server isn’t the cheapest and we don’t have an installation in-house. Thankfully one of our IT guys suggested SQL Express (a limited free version of SQL Server) as a possibility, and after a quick check on the AuthorIT Yahoo Group, I’ve found that it will run quite happily on that database.

There is a limit of 4GB on the database size but as long as we keep our images elsewhere there is little chance we’ll hit that limit. Our total content at present, including images, tops out under 500MB for one version of the documentation. So we’ll actually be saving space on a server as we won’t be maintaining multiple versions of entire documents. Must remember to point that out to our IT guys!

Aside from versioning the only feature I was unfamiliar with was the batch runner, which allows you to run a batch file (.bat) as a scheduled task. Our current system runs at night, using Webworks to create a Javahelp file which is then included in the software build and AuthorIT will give us similar functionality.

Why AuthorIT? Well, quite simply it gives us what we need.

I spent some time at the X-Pubs conference last year, and throughout the presentations the underlying message was “get your requirements sorted before hunting for a system”. The premise is obvious enough, if you decide on a system first, you end up shoe-horning your processes around how it works rather than getting a system that works you way YOU work.

I also spent some time considering DITA but ultimately switching to an XML-based system is still too cost-prohibitive. AuthorIT is a compromise, allowing us to work how we want to work, whilst giving us single source benefits. We will use DITA as a framework for how we plan and write the content, but the simple fact is that AuthorIT is a much better value proposition than a bespoke system, both in monetary and resource terms. This makes the business case much easier to sell.

If you are considering single sourcing your content, then I’d strongly suggest you investigate AuthorIT as a possibility. It has limitations, including the oft-cited reliance on Word as a publishing engine, but for me the advantages outweight those.

And no, I am not being paid to endorse AuthorIT.

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 I’m also toying with writing up an article or two for the ISTC magazine, Communicator. As ever, those will be the first things to go when project deadlines need to be met, but I’ll give it a try. One thing I won’t be doing is undertaking an MA in Technical Communications. The course starts this month and there is just too much going on in my life at the moment… maybe I’ll join the September influx. We’ll see.

I will, of course, be expanding on the themes I’ve been posting about recently, specifically the role of the modern Technical Communicator in a forward-facing software company. I’m hoping to make some strides in this area and I’ll be sure to write up my thoughts on a variety of topics. I’m also hoping to hear more from YOU, dear reader. Whilst I did start this blog as a way of getting my own thoughts straight, it’s been great to read your comments over the past year. Blogging is all about the conversation, so please, don’t be shy.

Here’s to a wonderful year!

Right, I’m off to write up that article I had completely forgotten about.