ffeathers — a technical writer’s blog

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. In one of the sessions today, Sarah Goodall walked us through a DITA application developed and implemented by Tactics Consulting under consultation with Tony Self from HyperWrite.

This session was interesting as a practical application of DITA and as an application which is not primarily a technical documentation system. Tactics developed a DITA-based system to create and store proposals. Before the new system was implemented, the creation of proposals was largely a manual process involving copying and pasting information from similar proposals in Word documents. This could lead to inconsistencies and even inaccuracies.

The proposed solution was a single-source XML-based solution. Tactics chose DITA because they saw a lot of commonality between DITA and Information Mapping, the technology used and promoted by Tactics. It was relatively straight forward to map DITA information types to the Information Mapping types. Also, Tactics was keen to use an open source solution, and one that they can share with their customers.

As a next step, Tactics plan to move even further into single sourcing, by drawing their web site content from the same source as their proposal documents, brochures, etc.

Sarah’s presentation was interesting from the technology side of things. She also mentioned other aspects of the project, such as change management — moving the staff to the new procedures and technologies.

A couple of snippets:

• Elkera XML Print is an Australian product that renders DITA into Microsoft Word.
• I raised the point that people often don’t like to see the same information thrown back at them in different media. For example, if they see some information on a brochure they might go to the web site for more in-depth information or to see the same information but worded differently. They find it annoying to see exactly the same words. So while you can use conditional tagging to include more or less information, would you also need to ensure that the wording itself is different and is this a design consideration? Sarah Goodall replied that Tactics will continually test their users’ responses to the content, and supply different content for different media if necessary.

Thank you Sarah (Goodall) for an interesting and useful session!

BTW, there are eight Sarahs at this session, in a total of 65 attendees

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. One of the sessions today covered web technology and standards, presented by Joe Welinske.

Joe is the president of Seattle-based WritersUA. This is the second of his sessions that I’ve attended. The first is covered in my earlier blog post, on trends, tools and technologies in online documentation. Today’s session was more technical, covering various standards in the following groups:

• W3C standards such as HTML, XHTML, XML/XSL, Web Accessibility Initiative, CSS.
• W3C hybrids such as HTML 5 (more below), AJAX, RSS and jQuery.
• OASIS technologies — DocBook and DITA.
• Other open source technologies — Oracle Help, IBM WebSphere.
• Proprietary technologies that are still relevant and useful because they are so widely adopted and stable, such as Adobe PDF, AIR and even Microsoft Silverlight (emerging)

As well as talking about the above standards, Joe discussed each one’s possible application to technical communication.

In this blog post, I’ve extracted the subjects that were new to me and a couple of interesting items. Joe covered a lot more than I’ve mentioned here.

HTML 5

HTML 5 is an emerging standard that Joe feels we need to keep on our radar. It’s also known as “Web Applications 1.0″. It includes capabilities that are relevant to technical writers. Specifically, it supports new modular objects as part of a web page e.g. <aside>, <article>, <nav>. So a web page can recognise chunks of content in a non-linear way. Here’s a link Joe gave us to a demonstration: HTML 5 Support by Browser

I found this really interesting, after all the discussion in previous sessions about modular documentation and structured authoring.

Joe thinks that, because HTML 5 has a high amount of interest from some big players, it will probably go ahead.

A question from the floor led to a discussion around HTML’s leniency as opposed to the strictness of XML / XHTML. So HTML 5 may meld HTML’s leniency with the semantic tagging provided by XML. This is potentially useful for the less-technically-savvy authors, because the browsers and other viewers will be instructed to render a page if at all possible even if it contains formatting errors.

Other snippets

Some more interesting items from Joe’s talk:

• Comparison of XML rendering via XSL versus CSS: Printing XML: Why CSS Is Better than XSL.
• Neat use of Flash for an online tutorial, from Verizon Wireless — demonstrates how to use a mobile phone. Click the ‘Interactive “How To” Simulator’. It has a movie of a hand clicking the buttons, plus a block of text in the right-hand panel. The text is in sync with the movie, and you can influence the movie by clicking the text.

My conclusions

Joe covered a huge area in this short session, and his knowledge is huge too. Thank you Joe! The next two days of the conference include other sessions with more detail on some of the areas which Joe has introduced, including one on AIR (Adobe Integrated Runtime) tomorrow.

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. Today Jonathan Halls spoke about the new media and multimedia, and how things are changing in the world of communication.

Jonathan is chairman of Talkshow Communication Ltd. His presentation style is charming and funny and he tells a good story. At this session, he talked about the changes in our way of life and communication style, which mean that we technical communicators need a new “grammar”. His definition of a grammar is “the principles or rules of an art, science or technique”.

There are no rules for this new grammar yet. It is up to us, the technical communicators, to write the new grammar. What’s more, instead of looking to write a set of rules, we should be looking for the right list of questions.

Some titbits

These are some interesting nuggets of information from Jonathan’s talk:

• Kids don’t use capital letters any more.
• Think about teenagers’ concentration spans and multi-tasking abilities — if we write the way we were taught to, they’re not taking it in.
• On a web page, the average person reads 200 words then stops.
• What do you think is the typical demographic of Second Life? One person in the audience responded quickly with “People who don’t have a first life”. The interesting answer is: People aged 35 to 45, Northern European, who are high earners.
• 25% of kids use “lol” and emoticons in their schoolwork.

Evolution of the story

Jonathan does tell a good story. While telling us a story of a caveman’s conversation with his wife, Jonathan also pointed out how story telling has moved from the interactive, multi-media and non-linear style a caveman would have used, through the recorded, narrative style made possible and enforced by writing and the printing-press, through film and radio, to the web. We’ve now come full circle, because the web allows us to combine the media and tell an interactive, non-linear story again.

Principles for the new grammar

Moving back to the new grammar we need, Jonathan listed five principles:

• Multiple methods, or multimedia — we need to make sure we understand what works where.
• Moving from a linear to a non-linear narrative — becoming more conversational and acknowledging the fact that the audience doesn’t necessarily want to read the whole document. Blogs, wikis, forums. This ties in neatly with the DITA workshop I attended and blogged about yesterday — technology enabling modular documentation.
• Interactive participation — yielding control back to your reader; communication is becoming more personal.
• Shared authorship — wikis; using amateur writers to add value; acknowledging that you as technical communicator can’t do it all alone.
• Shift of your audience to a community — wikis and blogs again.

My conclusions

Jonathan’s talk brought home the way our lifestyles and communication methods have changed over the last fifteen years. I personally am lucky that I’m working in an environment which already uses much of the technology he mentioned. Even so, the message is clear: Keep innovating, keep thinking of new ways of doing things, and don’t get trapped into a paradigm where our new methods are bounded by the traditional ways.

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. Yesterday afternoon, Joe Welinske presented a session entitled “Trends, tools, technologies in online documentation”.

Joe is the president of Seattle-based WritersUA. Yesterday’s session gave us some good insights and discussion points based on the results of the WritersUA Skills and Technologies Survey. I’d recommend a quick look at the results on the linked web page.

General points

Here are some points from Joe’s talk which I found particularly interesting.

• Looking at the user assistance skill set, a list of things we technical writers do — it’s a long list, though it does fit on one slide Joe asked us whether we had all done most of the things listed. I have, and I think most people had too, in the course of their careers in technical documentation.
• Tools — Adobe controls 60% of the tools we use. Madcap Flare’s market share keeps growing.
• Skills we need for online documentation — include technical geeky things like XML, XSL, XHTML, DITA as well as the core skills like HTML, CSS, graphics etc.
• How we get training in these skills — 64% from on-the-job training. 22% by learning on your own. This confirms my own experience.
• Publication media — More than half of the respondents said that they preferred printed manuals! Also, 83% indicated Adobe Acrobat, which is close to printed manuals. Embedded user assistance is on the rise.
• IBM is working towards replacing Eclipse Help with DITA Help.

Analysis of help in Microsoft Vista

Joe walked us through a very interesting analysis of user assistance in Vista, as a method of divining Microsoft’s direction for the future of help in Windows and their idea of best practice.

HTML Help was first released in 1996, and updated in 1998. Since then it has kind of stagnated. Yet it’s still Microsoft’s recommendation for online help development.

The online help in Vista:

• Presents in a single window — no separate panel for navigation bar / table of contents.
• Has no index.
• Uses search as the main navigational component. This may work if the search is good, but is tiresome if you get too many hits.
• Includes a lot of rich information. Microsoft is not going for minimalism in their documentation.

Also, Vista embeds a lot of traditional help content right on the UI, as text on the screens. The goal is to make help unnecessary wherever feasible. This means that technical writers must be involved in the UI design. We must be able to put ourselves forward at design time and say, “This is something I’m really good at.”

Other developments technical writers must be aware of

Technical writers and communicators need to keep in touch with new developments and philosophies, such as:

• Mashups — integrated, unrelated applications, which will need online documentation of some form or other.
• Web-based API documentation — growing demand. Google is a big employer of technical writers in this area.
• Custom devices — OLPC (One Laptop per Child), PDAs, phones, other mobile platforms. How can we deliver documentation that works on these platforms?
• Structured authoring — affects a growing number of technical writers. Joe sees this as the most important concept for us to learn about. It affects our roles and production process. The author works in a form-based environment, putting the content into pre-determined pigeonholes. Presentation is separate and automated.
• Web 2.0 — collaboration and the ability of our readers to interact with the content. We need to wrap our heads around what this means for documentation.

My conclusions

Thank you Joe for a great overview. I’m looking forward to hearing more from Joe in the next few days of the conference.