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.

Give me your technical writers yearning to breathe free

We've two clients, one in France and the other in Denmark, willing to hire US American and Canadian technical writers who have the skills they need. Salaries are up to $150,000 pa.

There are approximately 1,500,000 Americans of Danish origin or descent,according to Wikipedia, so this could be a homecoming of sorts.

See the Vacancies page on our web site for more details.

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.

(continues)

User Assistance - You've come a long way baby?

The MgmtSIG digest pointed me towards the Bitsavers' Software Archive (http://www.bitsavers.org/), 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 - http://users.edte.utwente.nl/meij/smalltalk.pdf). 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 Ted.com) 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?

What's brewing with MadCap and DITA?

MadCap are sending out a mailing to its database today with the words:

MadCap DITA
10-29-08

The link sends you to the MadCap Web site, but provides no other information.

I guess we'll have to wait a week until we know more.

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.

Augmented reality gets closer

Earlier in the year we blogged on Nokia's plans for augmented reality and how it could be used for user assistance. Developments are moving apace, as can been seen by this demonstration from Japan:

The rights of the technical reader

At the Roald Dahl museum there is a poster on the wall entitled "The rights of the reader". It's a wonderful ten point manifesto drawn up by Daniel Pennac in his book of the same name.


Unfortunately, the poster appears to be no longer available for download from the Walker books Web site, but it is available elsewhere.

The rights include:

The right to skip
The right to read anywhere
The right not to finish

Would any of the rights differ for a technical reader?
------
(Addendum)

Our thoughts were:

The right to read in a medium that suits me
The right to be listened to
The right to up to date information
The right to expect the information will be understandable
The right to be able to find the information I need

What would be the corresponding rights be for the technical writer?

Our thoughts were:

The right to be given enough time
The right to be given accurate information
The right to have correct tools for the job

Does the Google Chrome browser show Web based Help correctly?

We took a quick look at Google's new Chrome browser this morning. MadCap's Flare Web based Help seems to work fine, but there seems to be a problem with RoboHelp's Web Help - specifically the Table of Contents.

We dragged some old RoboHelp 5 generated Web Help files into the browser, and we looked at some of the examples listed on Adobe's Web site (http://www.adobe.com/products/robohelp/customer_examples/). We haven't had a chance to do any further testing.

Update - The problem is also there with RoboHelp 6 generated Web-based Help.

We suspect it is a JavaScript with Frames issue. The "Section 508" (non-JavaScript) version displays without any problems.

Wikis instead of Help?

Zoho has decided to use its own wiki to provide online Help instead of Help created in RoboHelp. They have posted on their blog the reasons why they have done this, together with the benefits resulting from this change.

This is what the help looks like now.

We're not anti wikis and we're not pro RoboHelp, but nearly all the benefits seem to relate to how the Help was produced and not to what was delivered.
For example:
With a move to a wiki, the users seem to have lost a table of contents that follows where you are in the document.
The individual pages are very very long, unlike the short screen size pages normally you get with RoboHelp generated Help.
There's no pop-up Help topics (for things like glossary descriptions).

These problems may be down to bad information design rather than technical limitations, but it seems fair to say that this change has brought disadvantages as well as advantages with it.