ffeathers — a technical writer’s blog

The Australian Cultural Evening (ACE) is a not-to-be-missed event at the annual WritersUA conference. I was privileged to attend the ACE during WritersUA 2009. Tony usually writes about each event in hilarious detail (here’s his report from last year) so I’ll restrain myself to a few words and some photographs.

The ACE is restricted to Australians, erstwhile Australians, would-be Australians, anyone who has any Australian connection and people who have no connection whatsoever. This year there was an added restriction: “No kiwis!”

Another term for the ACE might be “pub crawl”, interspersed with a few mandatory “Aussie Aussie Aussie Oy Oy Oy” chants. It’s fun. Do it!

We started off at the Westin Hotel. Note the “Aussie Aussie Aussie” t-shirt:

Australian Cultural Evening at WritersUA 2009

Me see no evil:

Australian Cultural Evening at WritersUA 2009

Our next stop was the Blarney Stone Pub:

Australian Cultural Evening at WritersUA 2009

Birthday boy:

Australian Cultural Evening at WritersUA 2009

The flag, aptly poised next to the draught beers ad:

Australian Cultural Evening at WritersUA 2009

Here I am (Matt D, this one’s for you ) with two ACE gents:

Australian Cultural Evening at WritersUA 2009

I left at this point. I was exhausted. My presentation had happened that day, the Westin had creaked and groaned in the wind all the previous night, and I’d slept very little. Returning from the Blarney Stone, I counted myself lucky to find my hotel room again, after getting mislaid in the South Tower while my room is in the North Tower.

I believe the party went on I’m looking forward to reading other people’s accounts. Thanks to everyone for a great evening!

Yesterday was the third and last day of the WritersUA 2009 conference in Seattle. It was been a full and interesting day, just like the other two! Here are my notes on the sessions I attended on the last day.

These are the sessions covered below:

• Exploring open source and alternative tools
• iPhone design and development overview
• Magic and mental models: Using illusion to simplify designs

Exploring open source and alternative tools

This was a joint session, present by Paul Mueller, president of UserAid, and Mike McCallister, author of openSUSE Linux Unleashed among other accomplishments. The session focused on how you can develop high-quality user assistance using open source tools.

First Paul gave us an overview of the different categories of tools available: Desk top publishers and editors; graphics editors; multimedia recorders; HATs; version control and data backup; remote access; webinars and concalls; collaboration; bug tracking; reviews; web services; email management.

For each category, he gave us a list of possible tools, including commercial and free. He also touched on the considerations when choosing a tool e.g. does the output deliver a standard file; does the output meet the company requirements; how many users need access, and so on.

Paul mentioned Google Docs as something we should follow. The US government is evaluating this option.

He gave us many tips for specific tools, and I just jotted down a few that interested me particularly.

• Some free tools for multimedia recorders: Wink; Audacity for podcasts.
• Free PDF generators: Acrobat.com; CutePDF
• Free webinars: Acrobat.com (allows screensharing for up to 3 people); InstantConference.com (free for up to 150 users; allows you to record).
• Free chat: IM with SIMP at www.secway.com (free and secure)
• Coding tools: HomeSite with TopStyle is Paul’s tool of choice ($100; www.adobe.com)

Mike McCallister now took over to demo some of the open source tools. He did a great job of a difficult task: demoing five open source tools in a short session. All the tools that Mike demonstrated will run on Windows, Mac and Linux.

Here are my notes on some of what Mike showed us:

• OpenOffice Writer: By default, Writer writes to ODF. Any other software should be able to read it. (Microsoft Office not yet, but promised by this autumn.) Includes a direct PDF export. List numbering works very well. “No surprises ever.”
• OpenOffice Web gives you cleaner code than Word.
• Scribus open source desktop publisher — You create your document in another tool then publish it with Scribus. You can do simple text in Scribus, but the rest is authored elsewhere and imported. Mike really likes it for short manuals and quick reference guides.
• LyX is the GUI for TeX and LaTeX. Created for UNIX. WYSIWYM — “what you see is what you mean”. Has a great equation editor. Complete separation of content and presentation. The documentation is terrific too. Terminology is slightly different. A template is called a “document class”. A style is called an “environment” and is strictly enforced by your class.
• The GIMP is a terrific raster graphics editor. It does layers, takes screenshots, and is now beginning to support the CMYK palette. You can even create styles for layers. It supports the standard scripting languages and has many useful plugins. It covers the more obscure uses for a graphic editor The main issue is that the terminology is a bit different, which can be a problem when moving from PhotoShop to GIMP. GimpShop attempts to bridge the gap by translating the terminology, but it’s not up to date.
• Inkscape is a vector graphics tool. Outputs standard W3C XML. Has some smart objects to help with flowcharts. Inkscape includes a built-in IM support client that sends you straight into the Inkscape support team chat room! Inkscape has its own XML editor so you can add/adjust attributes etc.

Lastly, Mike gave us a link to a resource providing a list of open source tools and downloadable files: The OpenDisc.

iPhone design and development overview

Christopher Z Garrett of ZWorkbench is an iPhone developer. He discussed the steps you should take if you’d like to start developing iPhone applications (apps) and demonstrated some apps with good and bad features.

Here are my notes from his session:

• Many major brands are now wanting to be on the iPhone platform, such as the big social networking sites.
• Some interesting statistics just received from Apple: 30 000 000 iPhones and iPod touches sold; 25 000 iPhone apps on the AppStore; 800 000 000 app downloads.
• To develop for the iPhone, you need a Mac as well as an iPhone. You cannot do iPhone development on Windows.
• Tip: Review as many apps as you can — at least 100 of them. Start learning what works and what doesn’t work, and learning the user interface.

Christopher took us through a couple of applications, without being too critical. To do this, he put a phone on an overhead projector and showed his actions in real time:

• Amazon have released a couple of apps that are less than optimal. Christopher demonstrated the Amazon shopping app. When viewing the wish list, you cannot scroll up and down by flicking. The row of items on your wish list actually scrolls horizontally, and there is no indication that it does this. This breaks the Apple standards. The search is also non-standard, in that it overlays the current page.
• You need to make sure you stick with the Apple mobile phone standards in your app design. Even if the Apple web site works differently from the iPhone, or if you are tempted to follow the conventions on your own company web site, you should rather follow the iPhone conventions.
• Looking at the USA Today app: when you ask to see today’s hourly forecast, it asks if you want to launch weather.com. This will close the app and open Safari. This looks as if USA Today has just been too lazy to include the weather. Instead, they should embed web content inside the app, so that it opens in a separate window within the app.
• Another app: Trapster (finds speed traps) requires a long and painful signup process. Most of the time, as an iPhone app, you really don’t need a signup process because there’s no need to keep track of the user in order to store settings.
• Trapster also presents lots of text to read. Remember, you’re supposed to be using this app while driving.
• So the message is: Read the Apple user interface guidelines and follow the conventions used in most apps.

Christopher also showed an example of good help for an iPhone app: A Tower Defense game. The help shows screenshots and very simple instructions. Very little text.

Next Christopher showed him some of his own apps:

• The Oxford American Dictionary is one of his clients, for whom he has created an iPhone app. The dictionary on the phone contains 350 000 entries, i.e. the entire dictionary is stored on the phone. It took a lot of effort to get the app to react fast, finding the words as you type. When designing the browse interface, he imitated the way a normal dictionary (i.e. a book) works. First he looked at other dictionary apps on the iPhone, to see their mistakes.
• Next he showed a game his sister developed. The help is very simple. It says things like “Whack me”, “Shake me”, etc and then rewards people by saying “Good job” if they get it right. Accompanied by cute pictures. This is ideal help.
• Christopher’s favourite app is Ocarina. This app allows you to turn your phone into a musical instrument. It has a world view that is totally cool. You can listen to what other people are playing over the world. It picks people at random. You can press a heart button to send them love. The app is really simple, but the instructions are more complex because turning a phone into a musical instrument is complex. They’ve done everything they can to make the instructions simple. The help also tells you where you can see some examples. And it has a video tutorial.

So there’s absolutely a need for user assistance on a platform like the iPhone. But we don’t need lots of text. It’s a very different kind of need.

Magic and mental models: Using illusion to simplify designs

This was the last session of the conference, and it was a blast. Under the pretence of educating us about the relationship between user assistance design and magic shows, Jared Spool showed us some very convincing magic tricks and had us rolling in the aisles.

And yes, he did convincingly illustrate the relationship between magic, mental models and user assistance design!

Here’s a picture of Jared asking Joe Welinske, president of WritersUA, to gaze into the distance while the rest of us looked into the spinning disk that Jared is holding:

WritersUA 2009 day 3

After we had gazed into the spinning disk for a count of ten, we all looked at Joe and burst out laughing. His head was expanding! Of course, poor Joe had no idea why he was suddenly the object of such mirth.

The reason for Joe’s expanding head: Your eye muscles start to fight the motion of the spinning disk. When we looked at Joe, our muscles needed to relax because his head wasn’t spinning.

Jared’s theme was perception: how people’s perceptions differ depending on circumstances, and how we can take advantage of this fact when designing user assistance material.

Here are my notes. Look out for the long-running magic trick that Jared conducted during the session

• Jared was introduced to magic when his son has become a professional magician. Jared realised that the process of putting together illusions is very similar to the things we talk about when putting together great user assistance designs.
• A mind-reading trick: Jared tried out a trick that he’d heard about. Unfortunately, he’s missed the first part of the session where this trick was explained, but he thought it would work anyway. He picked a member of the audience (Amy) and asked her to think hard about her favourite type of food. Then he concentrated and wrote diligently on a piece of paper. When he asked Amy what she had thought of, she said pizza. He looked disappointed and crumpled up his piece of paper, saying, “I guess I should have been there at the beginning of the training session.”
• Next he tried a card trick. He displayed a number of cards on the screen and asked us all to choose one silently. Then he displayed 5 cards, saying that they would exclude the cards we had chosen. We were all amazed that our cards weren’t there. Actually, his second display was of 5 other cards that were not in the original set at all. Reason this works: We were focused on choosing a card, not on the set of cards. Our mental model was different to his.
• In the same way, a user’s mental model is often different to the designer’s model.
• Good magicians make a trick interesting even to people who know how it’s done, because they think of new ways to do it or because they do it so gracefully. That’s what illusion is about: Creating two separate models and maintaining them separately.
• Storage of files on disk, and deletion of files, is all an illusion. There are no actual files on disk, just a series of zeroes and ones.
• Flickr URLS are not representative of how the data is actually stored. But they give the illusion that they are.
• Back to the mind-reading trick: Now Jared asked Chris from the audience to think of his favourite colour but not say it out loud. Again Jared wrote something on a piece of paper, then asked Chris to tell us the answer: “Orange”. Jared responded, “Damn it, I really should have been there at the beginning of the session.”
• This is where Jared did the trick with the spinning disk and Joe’s expanding head, shown in my photograph above. So, the way we perceive things is important.
• Perception of time is especially problematic. For example, put a progress bar on a screen to show people what’s happening. Even if the progress bar actually slows down the processing, people will perceive it as faster.
• Perceived performance time is based on success of task completion rather than on actual download time. Time goes slower when it’s painful.
• Designers can make use of a user’s perception, e.g. by starting a task as soon as possible (e.g. video streaming) so that there’s no painful wait.
• Proximity is really important too. Don’t disperse the information or input fields. For example on a login screen, don’t separate the username, password etc.
• Trying his mind-reading trick again, Jared now asked another audience member, Bob, to choose a card. Bob chose the ace of hearts. Again, Jared got it wrong.
• So we took a look at the Kano model: At some point when designing a product, you cannot keep raising user satisfaction by adding new features. But you can aim for a sense of delight. It does not even have to be anything big. Just an excitement generator.
• Guess what, Jared’s mind-reading trick had actually worked. Towards the end of the presentation, he showed us crumpled up pieces of paper where he had actually written “pizza”, “orange” and “ace of hearts”! The trick is that he had actually written them in reverse order, starting with the ace of hearts which came from a pack of cards consisting entirely of the same card. So he wrote “ace of hearts” when pretending to read Amy’s mind, then he wrote “pizza” during Chris’s turn, and he wrote “orange” for Bob.
• This trick produced delight in us, his audience, because he had managed it in the middle of his presentation.
• An example of delight: In iTunes, your iPod nano will show up as an icon with the correct colour and model, reflecting your very device. Attention to detail.
• Jared noted that in order to get the “delight” part right, you need to get the basics right first.
• A concept that is key to design: People like to have magic in their lives.

Other people writing about the WritersUA conference

Rhonda Bracey has written some great summaries on her blog. Here’s her latest blog post. And here’s the WritersUA 2009 Conference Blog.

Happy reading about this excellent conference!

This week I’m attending the WritersUA 2009 conference in Seattle. Yesterday was day 2 of this very enjoyable conference. I’ve talked to so many great people and lots of interesting sessions. Here are my notes on some of them.

Sessions covered below:

• Microsoft 2.0: What to expect in the post-Gates era
• Using a wiki with modular and conditionally publishable content
• Delivering open-source technical documentation through a wiki
• Delivering enterprise technical documentation through a wiki

Microsoft 2.0: What to expect in the post-Gates era

This was the first session on Tuesday, featuring an interview with Mary-Jo Foley, blogger on ZDNet, journalist and well-known commentator on all things Microsoft. Matthew Ellison hosted the session. He posed some great questions and kept the session flowing very easily.

I found Mary-Jo’s style engaging, energetic and to the point. She told us of the early days when she first started tracking activities in Microsoft. One of her early fact-gathering techniques was to catch a ride on the Microsoft shuttle bus and listen in to what people were talking about. Eventually they posted her picture at the bus stops and instructed people not to let her onto the bus.

Background information from me: Bill Gates stepped down as CEO of Microsoft early in the year 2000. Until June 2006, he stayed on as chairman and chief software architect. In June 2006 he started moving away from full-time work at Microsoft, putting more of his energy into the Bill & Melinda Gates Foundation. He gradually handed over his duties to Ray Ozzie, chief software architect, and Craig Mundie, chief research and strategy officer. Currently Bill Gates is still the non-executive chairman. Steve Ballmer is current CEO.

Here are my notes from the session with Mary-Jo, where she discussed how Microsoft plans to stay relevant in the post-Gates era:

• Ray Ozzie is a well-known software developer, who created Lotus Notes among other achievements. He is someone Microsoft always wanted to hire. They eventually got him by buying his company. As chief software architect, Ozzie now sets the strategic direction for Microsoft and is the new public face of Microsoft. But he’s very shy. He hates to speak in public. He’s an engineer’s engineer.
• If you want to gain some insight into Microsoft’s strategy, take a look at the Internet Services Disruption memo of October 2005. Ozzie wrote it about 5-6 months after he joined Microsoft. It has quite a different tone to previous communications, and suggests that Microsoft should be more open,  Windows shouldn’t be proprietary, etc. Mary-Jo says Microsoft  is now doing exactly what Ozzie outlined in that document.
• Who’s on the short list of candidates to take over as CEO when Steve Ballmer leaves? Kevin Turner, current COO (but not popular within Microsoft);  Robbie Bach, head of the entertainment division (Xbox etc); Stephen Elop, a recent hire who now runs the Office division (still the most profitable division of Microsoft). Mary-Jo thinks they may even recruit from outside, when Steve Ballmer eventually steps down as CEO. But he’s not going anywhere for the next 10 years or so.
• What are Microsoft employees like? Well, 95000 people work at Microsoft (“Softies”), all over the world. So it’s hard to characterise them. Mary-Jo describes “Softies” as paranoid, but in a good way. “How do we suck?” That’s a question they often ask their competitors and customers. She also describes them as arrogant, especially the old guard. They believe they are the smartest people in technology. This combination makes them fascinating to write about.
• There has been a market change in the period since Gates reduced his day-to-day duties. The emphasis has moved from science to business. Gates rewarded and concentrated on geeks — engineering. Steve is more focused on business — sales and marketing.
• Usability is the new holy grail. Microsoft  is starting to value it more.
• How about openness? Mary-Jo says that rather than attempting to be transparent, Microsoft  is attempting to be translucent. They want to be more like Apple: retain secrecy around new products, then make a big announcement. So Microsoft needs to be a lot more secretive than they have been in the past. Stop leaks.
• Mary Jo has a PDF file containing the Microsoft project code names, which she tracks. You can download it from her web site. I haven’t found it yet, but I have found a list of related blog posts on the ZDNet blog.
• Microsoft is moving towards consumer products. The theory is that if you can hook people via their home products, they are more likely to buy your business products. So there’s more emphasis on consumer version of Windows, Xbox, etc. We’ll see more and more of this over time. Also Microsoft feels that the big breakthroughs, especially in social media and new technologies, are happening first on the consumer side and then adapted for the business world.
• How are the anti-trust judgements affecting Microsoft development policy? Windows 7 has a feature to allow you to unbundle some of its features e.g. you can choose to remove IE or add third-party features. This is an effect of the anti-trust laws and a concern about being sued if they put too much into a new product.
• Software as a Service (SAAS): The Microsoft view is to have customers install the software (e.g. Office) and then use the cloud for add-on features. Their opinion is that most businesses are not keen to put their data in the cloud. A “software plus services” business model.
• Mobile: Microsoft are lagging behind here. Windows Mobile 7 is coming out next year, but that’s a long time to wait. They have a lot of catch-up to do in the mobile space.
• Office 14 coming next year. PowerPoint, Excel, etc will work as web-based products. But this is not exactly the same as Google Docs because of ties into SharePoint.
• Microsoft is investigating what it would look like if Windows became a distributed operating system. This is a secret project inside Microsoft at the moment.
• They’re also looking into virtualisation for Windows, client and server.
• They’re trying different licensing modules e.g. advertisements along side in Office; monthly subscriptions.
• What are Microsoft excited about? The whole “touch” experience. They see themselves as innovative in this area. (Mary Jo would rather see them getting wild and enthusiastic about keyboards.)

Using a wiki with modular and conditionally publishable content

This was a very interesting session by Rahul Mehrotra from Agilent Technologies. He started by giving us an introduction to content management systems and ran us through his team’s process for evaluating CMS versus wiki. He and his team looked in particular at input, storage, output and workflow.

• Their first priority was to have just one tool. Everyone should use the same tool, and it should encompass input, storage, output and workflow.
• They had a look at DITA, and thus realised that they wanted modularity and conditional publishing. That became their second priority. (Note: They don’t use DITA. But they used it as a reference for ideas on modular content, conditional publishing and link management.)
• Seamless integration was essential. The tool must just work. No-one in the organisation would help them set it up. This became the third priority. They eventually moved to a wiki because the most complicated wiki to use is easier than the simplest content management tool.
• Ease of authoring is essential. Fourth priority. The people who were going to use the tool should not need any training. Collaboration is also important.
• Priority 5: Workflow. The documentation must be ready the same day as the product is ready to ship. They load the appropriate version of the documentation into the product via a nightly run.

Which wiki did they eventually choose? Atlassian Confluence, of course

(An aside: On Tuesday afternoon, after both our presentations were over, Rahul and I got together for an informal chat with some folk from Agilent’s Seattle office. I really enjoyed talking to them about their use of Confluence, about Seattle restaurants, and a lot of other stuff. They said it was cool to meet an Atlassian technical writer, and one who works on the Confluence documentation too.)

Going back to Rahul’s presentation: Rahul found it very interesting that “more people have embraced our wiki for its ease of use rather than for its bells and whistles.”

Rahul’s team have created a semi-automated process for bringing documentation into the wiki from almost any source. He sees this as one of the best choices they made in moving to the wiki. It also helped to move forward in terms of the adoption of the wiki by the developers and other teams in the organisation.

They have opened the wiki up for editing by everyone within the company. “It’s no longer our wiki, it’s everyone’s wiki.” The moment you let go the control, really good things start happening e.g. a developer creates a conversion interface from code to wiki markup.

Rahul gave us some excellent insights into problems they have run into now that they have conditional publishing and content re-use in their wiki. He finds that such customisations actually degrade the ease of use.

For example, their self-written conditional-use macro clobbers the WYSIWYG editor. So they have to add warnings to pages telling people not to use the WYSIWYG editor on affected pages.

Similarly with single sourcing, they have to tell people to click a link in order to edit the source of the content, rather than editing the page itself. Rahul pointed out that the Atlassian Confluence documentation is different, because it uses single sourcing right within the wiki.

I found this section of Rahul’s talk really interesting, because I could compare the way he has done things with the way we’ve chosen, and see the pros and cons in both methods. It was really cool that Rahul talked so frankly about the issues they’ve encountered when adopting a particular strategy and when choosing to depart from the simple wiki functionality.

Rahul gave us a lot more insight into his team’s publishing process and other aspects of wiki management. His was a really rich talk, with too much content to blog about here.

His parting shot was: “There are now 500 000 pages of content that 8 writers are able to take care of.” Magic.

Delivering open-source technical documentation through a wiki

Ragan Haggard of Sun Microsystems shared a “double scoop” session with me. He went first, speaking about the documentation for OpenDS. OpenDS itself is an open-source software development project. The documentation is on a wiki (JSPWiki) with a low barrier for others to contribute. There are two parts to the documentation: one for users and one for developers.

OpenDS is an open source project, so Ragan and his team wanted to use open source documentation too. Also, a wiki is a logical choice, because they want users to edit the documentation too.

They keep the entry barrier very low. A user must be registered in order to edit. The only reason to require a login is to prevent spam. People also have to click a button to accept the standard Sun terms.

Ragan talked us through the process of choosing a wiki. He strongly recommends a brainstorm session amongst the writers to get the list of requirements and prioritise them.

Next, they installed a few wikis to assess them. They eventually chose JSPWiki.

Ragan mentioned a few issues with this wiki:

• Creating nested numbered lists is very complicated. This is the same in all other wikis Ragan has seen, except Confluence. Confluence has easy bulleted lists.
• Renaming an article, i.e. changing the file name, is problematic. It needs to stay static, otherwise you break all links.
• JSPWiki has no email alerts, only RSS feeds.

For release management, Ragan’s team have set up a separate instance of the wiki for the previous version. This archive is not editable. (This is much the same strategy as we use at Atlassian, except that in Confluence we can use spaces within a single wiki rather than having to set up separate wiki instances.)

Ragan’s team have also created a branded version of the documentation, also not editable. This wiki is on a wikis.sun.com site, which is a Confluence wiki.

Ragan’s team exports the documentation to DocBook XML, to provide their hard-copy solution ,i.e. PDF. DocBook also allows syncing between the Confluence (sun.com) and the JSPWiki (community) wikis. The XML also supports conditional text for multiple versions.

Ragan said that there has not been a significant vandalism problem, even though the wiki is open for editing by anyone. The spam level has been low too. On the other hand, they have not yet received a large number of contributions. They’re starting to come in now, but no complete articles yet.

Ragan finished by saying that collaboration is the way of the future. We need to remove barriers for users to come and tell us their stories. This gives us valuable information, such as the different deployment scenarios.

Delivering enterprise technical documentation through a wiki

Next it was my turn. I spoke on the topic of “Delivering Enterprise Software Documentation through a Wiki”. I’ve put my notes in a separate blog post. There are also links for you to download the slides and the supplementary material for my talk.

That’s it for day 2

I hope these notes are useful. They cover yesterday’s sessions. Today is Wednesday, the last day of the conference and another full day of interesting sessions. I’ll blog about them soon

This week I’m attending the WritersUA 2009 conference in Seattle. Yesterday it was my turn to present a session. My talk was all about using a wiki for technical documentation. No, really?

My  approach was to introduce a number of topics that are relevant when you’re writing technical documentation on a wiki. I gave an overview of each topic and referred to my notes in the handouts. The slides and the handouts are attached to this blog post. Feel free to download them and use them to track down more information.

My main topics in this presentation were:

• An introduction to myself and my wiki — Confluence version 2.10
• Agile development — how a wiki is useful in an agile environment
• Workflow and tracking — a technical writer’s bread and butter, and how they work on a wiki
• Structure and chaos — a wiki may be seen as a chaotic environment, but we technical communicators need to bestow some structure on the documentation
• Release management — how your wiki documentation can relate to specific versions of your product
• Steering wiki development — how you as a technical writer can influence the features and development of wikis

I hope the slides and accompanying notes prove useful:

• Enterprise documentation on a wiki — slides plus notes
• Enterprise documentation on a wiki — slides only

This was the first time I’ve ever given a presentation at a conference, or anywhere else apart from team demonstrations. I had a bit of a battle with an iteratively-drooping microphone. But apart from that, the presentation went smoothly.

A big thank you to Joe Welinske and all the confererence organisers and attendees. I was rather nervous, but your warm welcome made it much easier and much more enjoyable than I was expecting. Thank you also especially to Joe for inviting me and giving me the opportunity to attend the conference and to visit the US for the first time.

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

Sunday meet-up

On Sunday evening we met at the Westin Seattle bar to see who’s here and say hallo.

WritersUA 2009 Day 1

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.

WritersUA 2009 Day 1

Moving on to some of the Monday sessions…

The Google Chrome Comic and Visual Communication

The first session of the day featured Scott McCloud, creator of the Google Chrome comic. Joe Welinske, president of WritersUA, interviewed Scott about his experiences creating the comic.

Here’s Scott chatting after the session:

WritersUA 2009 Day 1

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:

WritersUA 2009 Day 1

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:

WritersUA 2009 Day 1

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.