WritersUA 2009 Day 1
This week I’m attending the WritersUA 2009 conference in Seattle. This is a great conference with great people. There’s so much going on here that I can’t possible blog about it all. So I’m going to mention just a few sessions and post a few pictures. If you’re here too, awesome. If you aren’t here, I wish you were!
Sessions covered below:
- Sunday meet-up
- The Google Chrome Comic and Visual Communication
- An ISO/IEC standard for user assistance
- Creating help with DITA
- Microsoft Sandcastle documentation compiler
- Preview of Microsoft Help v.3
On Sunday evening we met at the Westin Seattle bar to see who’s here and say hallo.
There are more than 320 attendees this year. I’m sure there are other photographs floating around 🙂 If you have some, I’d love it if you would add a link in a comment on this blog post.
Moving on to some of the Monday sessions…
The Google Chrome Comic and Visual Communication
Here’s Scott chatting after the session:
Scott had some really interesting insights into the use of cartoons and drawings to convey a technical concept. He talked with great enthusiasm about the satisfaction he gets from translating a geeky concept into an understandable picture.
These are just some of the things Scott said:
- There’s a great overlap between geekery and comic books.
- You can always find a spacial metaphor (scale, separation, intersection, distance, relative height, etc) for whatever you are trying to represent, even if it’s a very abstract process you’re portraying.
- Two essential components of comics are sequence and the ability to isolate a single idea. You don’t see this so much in other forms of documentation. A comic has the ability to focus the mind on what you’re doing now. You really only need to know one thing at a time. A comic presents one frame at a time. An aeroplane safety card does the same thing.
- Static images seem to map to the way we remember things. They’re a natural mnemonic device. This is one of the reasons they use comics when your life depends on it, such as the airline safety cards.
- You need to avoid the “twin terrors” of content apologising for form, or form apologising for content. The first happens when form (such as a cartoon) is used to try to dumb down the content. The second happens when the form treats the content as a bitter pill.
The Q&A session brought some good stuff too, including discussion of the translation of comics; the ability to re-flow the comic if you need to change it for a later release; online (a long single flow) versus printed form. (The Google Chrome comic is designed for printing.)
Scott also fielded questions on Twitter, such as this one from Jim Campbell:
“The comic was released under Creative Commons. What prompted that, & what’s your reaction to some of the resulting mashups?”
Scott’s response was along these lines:
“The mashups were awesome! They had contests! There are thousands of pages out there. It was awesome!”
He also mentioned that the CC licence and mashups gave people a sense of shared ownership and made Google feel more accessible.
Here’s a slide from Scott’s presentation, including a shot of his own book Understanding Comics and an excerpt from the Google Chrome comic:
An ISO/IEC standard for user assistance
On behalf of Witold Suryn (who could not make it to the conference) Tony Self presented a session about ISO standards that support software user assistance.
Tony introduced a number of standards either under development or recently published, regarding technical documentation and user documentation. He concentrated on ISO 26514, describing who may/should use this standard, and how it’s important to us as technical communicators. The ISO standard covers writing standards, but also graphical design and layout. It may also be useful for managers, usability testers, etc, in that it establishes a framework for what you can expect from a document and covers all aspects of the documentation process.
This was a fairly dry topic. Tony presented it with his inimitable easy manner and helpful commentary, and surprisingly some good laughs. He finished by saying that these standards documents represent the distillation of a lot of knowledge, and are therefore useful if you want guidance on documentation development.
Creating help with DITA
Next Tony Self gave an overview of how DITA can be used to author and generate online help systems.
Here’s Tony explaining the DITA finches:
These are a few of the points Tony discussed:
- At this point in time, you can use DITA to produce basic content in some help systems, such as Eclipse Help and HTML Help, using the Open Toolkit.
- Still tricky at this point in time: Context-sensitive help. DITA metadata stores a context number, but not the context string. There are workarounds. Tony showed us an embedded context-sensitive help system within his own WinANT tool. His help system was of course written in DITA.
- To produce different output formats from DITA, you probably need to buy an authoring/publishing tool. You can produce HTML and basic PDF via the Open Toolkit.
- A new document will be available soon for download or reading online: It’s title will be along the lines of the DITA Help Technologies Guide. The document gives hints and advice on using DITA for help systems.
Microsoft Sandcastle documentation compiler
Anand Raman from Microsoft presented a very interesting short session on the Sandcastle documentation compiler.
You can use Sandcastle to document APIs. It’s described as a documentation compiler for managed class libraries. It works by extracting specific XML tags, such as <summary>…</summary>, included in the code and prefixed by three slashes to mark them as a comment “///”.
You can also develop other types of topics, such as “how to” topics, by authoring in a particular schema.
Sandcastle was originally built for the Visual Studio help system. It is now available as an open source project on CodePlex.
An interesting titbit: There are 20 million words and 300 000 topics in Visual Studio Help.
The next version of Sandcastle will support Microsoft Help 3.
Preview of Microsoft Help v.3
April Reagan of Microsoft gave us a frank and interesting look behind the scenes at the planning and design that has gone into version 3 of Microsoft Help.
One drawback of this session was that there was no actual help system to demonstrate. Still, I was impressed by the openness and frankness with which April tackled her topic.
Here are some notes I took, in a fairly unedited format because I’m running out of time. I hope they’re interesting 🙂
- April gave a very frank report of the feedback they have received on Microsoft Help 2. For example, “This is the worst help system I have ever seen”. Gripes about usability and performance.
- She showed us the results of user studies. There was an interesting graph showing what people have relied on to find information in Visual Studio: Usage of the index has grown steadily over time. Use of TOC has also grown. Use of F1 (to start help) has decreased. Use of the local Search (as opposed to a Google or other internet search) first grew and then dropped and has now flatlined at 10%.
- They used the above results to analyse the existing UI.
- The also took into account the fact that Microsoft has not delivered anything new in 10 years, for online help.
- So April interviewed users, talked to Microsoft teams and mined customer surveys and reviews, etc. She put together a “Help 3 Team Charter” i.e. priorities of what they want to accomplish.
- The result is Help 3.
- Help 3 promises a number of goodies, some of which are: provide a transparent and extensible API; build on standard technologies; present multiple versions elegantly; provide adownloadable SDK for developing help for Microsoft platforms; easy integration with Microsoft applications.
- Help 3 will follow a multiple release strategy: First version of Help 3 will ship in Visual Studio 2010. Will not yet include all the goodies, and support for some of the goodies will be only partial. The first version will have: Simplified viewer; security and reliability; standard technologies; part of multiple versions, and more.
- The Help 3 team have built their own custom client search, because other searches did not suit their needs. Windows search on your box supports one catalog; they did not want to negatively impact the other searches.
- Base for Help 3 is XHTML. It uses Zip files – that’s what you’ll see on your disk drive, plus the index fragment.
- Help 3 includes the index/search, protocol, viewer. It currently interacts with Visual Studio.
- The TOC etc, are all managed via attributes in the help topic. So the topic has the following metadata: Product, version, locale, ID, title, F1 keyword, Index keywords, TOC parent, TOC order, (category, content filter — not yet) (and later – topic version and branding).
- Installing the help content: They’re not using Windows Installer, because it proved problematic. Instead, they have a custom installer doing a process that they call “Ripping Content”. Much quicker for Visual Studio help installation – a couple of minutes instead of 30 minutes using Help 2.
- MS-Xhelp protocol is a UrlMON protocol.
- Help 3 viewer uses a web browser presentation – does not tie people to using Windows on their box.
- No compiler. You zip your stuff, Help 3 indexes it for you, and off you go.
- Microsoft are currently talking to tools vendors, to let them know what they need to do to allow authoring and output of the stuff required to produce Help 3 output.
There’s more information in April’s blog.
More networking and fun
WritersUA presented us with breakfast, lunch and end-of-day drinks. Later I went out with a group of interesting people for dinner. We talked about wikis, brains, life and everything.