Super MadCap quite fantastic; are other tools atrocious?

With the imminent release of DITA support in MadCap Flare, will competing Help authoring tools (HATS) suddenly seem inadequate to the task of technical writing?

Where does this leave Adobe’s RoboHelp?

I suspect it will be difficult technically and commercially (Adobe also owns FrameMaker) for Adobe to add DITA support into RoboHelp.

If writers are collaborating on a project or if a Help system needs be localised into foreign languages, then RoboHelp and other HATS may well lose out to Flare.

However, if a sole author just needs to write a straightforward Help File, then many may not feel the need to change from the tool they use today.

So what would you do if you were Adobe?

I wonder if Adobe will choose to compete with MadCap in other ways. RoboHelp could become more of an online training, performance support, tool. Also, Adobe could bundle RoboHelp with FrameMaker at a price that makes Flare seem very expensive.

This, of course, may be all academic if the DITA standard isn’t taken up by more authors.

Who says documentation doesn’t matter?

From Ars Technica

Judge: Microsoft documentation unfit for US consumption

By John Timmer | Published: September 25, 2008 – 07:50PM CT

Microsoft may have made a big push to settle many of the antitrust actions facing it around the globe, but those efforts have run up against a major stumbling block: the company’s inability to document the protocols need to interoperate with its own software. Documentation problems got Microsoft in hot water with the EU, and they’re now the only reason it continues to be under court supervision in the aftermath of its antitrust settlement. But, despite having interoperability become a corporate strategy, its documentation efforts came under fire in a court hearing earlier today.

In the wake of antitrust actions, documentation of Microsoft technologies has become a method of allaying the concerns of legal authorities in both the US and EU. By providing documentation of the APIs and protocols used by its products, Microsoft would not only allow third-party and open-source software to interact better with Windows and other software, but potentially enable them to write replacements, in whole or in part, for Microsoft products. This, in theory, would enable more software companies to compete on equal terms with Redmond.

Unfortunately, the company has consistently had trouble with producing complete and useful documentation. As noted above, the company struggled to satisfy EU authorities that it was complying with the agreement—that was 2006. By 2008, documentation was rearing its ugly head in the US court system. Microsoft’s consent decree with the federal and state attorneys general was set to expire, and most of the conditions were allowed to. But Judge Colleen Kollar-Kotelly, who is overseeing the consent decree, ruled that Microsoft still hadn’t sufficiently documented some protocols, despite those documents having been due in 2003. As a result, the consent decree will remain in place at least until November of 2009.


User Assistance – You’ve come a long way baby?

The MgmtSIG digest pointed me towards the Bitsavers’ Software Archive (, which stores documentation and software for minicomputers and mainframes from the 1950s -1980s. It shows how far user assistance has come, particularly in terms of graphic design.

However, there are still areas where we could learn from the past. The digest referenced MiTTS (Minimalist Tutorial and Tools for Smalltalk – Apparently, this guide was a pioneer of the minimalist approach to documentation championed by John M. Carroll. It’s the main approach online Help authors and Web designers use today.

The document begins:

“This tutorial is deliberately different from other programming instruction you have seen. It does not start off with a long drill on syntax and an example program that prints “Hello World.” Instead, it allows you to experience Smalltalk as an integrated software environment for object-oriented programming. In this minimalist tutorial you learn Smalltalk by analyzing and enhancing a simple but real application, a blackjack card game. You climb the Smalltalk Mountain by starting at the top!”

This leads me onto the themes of my talk at the UA Conference Europe 2008, concerning how user documentation is likely to change in the future. I suggested we’re likely see these developments:

The findable manual – users can find the documentation when they search on Google.
The read/write manual – users can write content was well as read it.
The remixed manual – users can remix the manual to suit them.
The community/collaborative manual – users can comment and share ideas.
The distributed manual – the content will be republished to many different places
The manual as a portal – the manual is a launching pad to other related user assistance

The user assistance we produce today may look as antiquated as the Bitsavers’ examples sooner than we realise!

How can we make online Help as natural as breathing?

One of the themes of every Help related conference is that some users are reluctant to use Help. Help, as a word, implies failure and, it is said, Microsoft spent a lot of time trying unsuccessfully to come up with a better word to use.

Recently, I was pointed towards a presentation by Professor Dan Gilbert on happiness (on and a book called “How Children Learn” by John Holt. Dan Gilbert stated we are reluctant to learn from the experience of others. Holt stated chilfren are natural learners, and will learn more if we let them explore their worlds.

Could we incorporate their ideas into the ways that Help (or User Assistance) is delivered and provide a better solution?
Should we could get users to access user assistance information before they get stuck, or will users always try to muddle through?
Can we make content more imaginative, and would that help?

UA Conference Notes

Last week, we attended, exhibited and spoke at the UA conference Europe 08. It was probably the best conference I’ve attended.

1. There were some excellent case studies from Sonia Fuga of Northgate, Rachel Potts and Brian Harris of Red-Gate Software and Matthew Ellison (concerning IBM). Northgate’s approach of using WordPress for ratings and commenting on content was ingenious.

2. Buzzwords for the conference were “faceted tables of contents” and “role encroachment”. I was pleased to hear two speakers talk about the implementation of faceted tagging (to create custom “Help portal” pages and custom tables of contents), as I talked about these in my presentation at the ISTC conference in 2006. Back then, I talked about facets to be used in conjunction with a folksonomy, but the examples shown, in fact, used them in conjunction with a taxonomy created by the documentation team themselves. “Role encroachment” means people in other departments doing technical authoring work.

3. A lot of the talks were about improving the process and adopting new Web technologies. It seemed to me that this move was at the expense of the user experience – these new approaches lose some of the usability functions that come with traditional Help.

However, I think this is a price worth paying, for the moment at least. I didn’t get the impression that new technology was being introduced for the sake of it, but because it was making things overall better for users. Perhaps it’s case of some content being better than no content,even if it’s not presented in a perfect medium for the user.

4. I was impressed with the direction of the Help Authoring Tool vendors Adobe and MadCap. They seem to be developing software that will incorporate the emerging technologies.

5. I was worried that my presentation would be “old hat”, but I was pleased my presentation seemed to be well received. I was worried that everyone know about interesting approch used to create Floss manuals, for example, but that didn’t seem to be the case.

6. The controversy of the conference was probably when usability expert (and outsider) Leise Reichelt asked if the audience wrote manuals. It seemed to be a question laden with preconceived ideas as to what technical authors do. The answer isn’t that straightforward – it’s Yes, unless there’s a better alternative for delivering user assistance.

7. The consensus of the conference was a move towards:
A single, aggregated information portal
User interaction with the content through commenting and rating

In one case study this approach indicated a $15,000-$20,000/month reduction in support call costs – impressive results.