ffeathers — a technical writer’s blog

Last week I attended the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. This blog post is part of a series about some of the AODC sessions I attended.

Here are some notes I took from the session on content, standards, learning and SCORM, by Allyn Radford of Learn’ilities’. I hope these notes are useful to people who couldn’t be at the conference this year.

Content, Standards, Learning and SCORM

Allyn started by giving us some context of what is happening right now. Within content domains, the key themes of the information age are being adopted: Modularisation, specialisation, integration and interoperability. Our communication is changing in volume, purpose and channels. The emphasis is more on collaboration and less on expert-to-novice teaching. And there’s a stronger emphasis on openness.

Allyn says we need to rethink the focus of reusability. Now we have to reuse content across disciplines, and we have to assume that the content’s destination is unknown.

Everything is 2.0 and everything is social. We are living in a mash-up world. As an illustration, Allyn walked us through parts of Mashable, The Social Media Guide. It’s like a directory of mash-up sites that combine different data sources to produce some interesting conclusions, statistics and visualisations. One of Allyn’s favourites is the fun mash-up called If I dig a very big hole, where will I end up?

What are the implications for learning systems?

We are looking at moving from monolithic learning applications to modular services, across different sources and services.

Learning content and organisational content should no longer be seen as two separate things. Marketing information, specifications, etc, can also be used in learning material or in brochures. So you start to develop a whole different appreciation of how you determine the value of content in your organisation.

Content is one of the most expensive things an organisation will create, compared to the technology systems that support that content.

There has to be a bi-directional relationship between three key things: The content, the process/practice used to create the content, and the technology infrastructure. Before you create content, you need to set up procedures for how that content will be maintained in the future.

What’s the role of standards in all this?

Interoperability, reuseability, maintainability — all the “ilities”. (Hence the name of Allyn’s company.)

Management of content is key. Traditionally in learning systems, not enough effort has been put into this.

Allyn showed us a list of standards related to LET (Learning, Education and Training). One of them is SCORM (Shareable Content Object Reference Model). Allyn listed these 6 key concepts that SCORM was designed to support:

• Interoperability
• Accessibility (different devices and locations, as needed)
• Reusability
• Durability (content must outlast changes in technology)
• Maintainability
• Adaptability

SCORM allows you to take courses from one learning system, where they were developed, and put them into other learning systems where required.

Granularity and reusability are interrelated. You need to consider reuse versus context. You lose context as your content become more granular. So you have to find the best mix for your environment, depending how important context is to you.

Allyn says that the problem with most existing standards is a “walled garden” attitude. This does not work well with the move towards open standards. There are significant costs to development and adoption of standards.  The “no-strings-attached” licensing is essential in LET standards.

Allyn works primarily with LETSI at the moment. The LETSI model is very open. LETSI does not develop standards, but works towards the adoption of available standards in learning technology and related fields like HR and Knowledge Management. It focuses on the interstitial work i.e. the bits that need to happen between the existing systems.

LETSI was asked to look at what “SCORM 2.0″ might look like, focusing on interoperability. They started reconceptualising what was actually happening, in the areas of learning activities, resources, people and competency frameworks. It turns out that SCORM 2.0 is nothing like previous versions of SCORM.

Nowadays, people in universities and schools are not locked into a particular learning management system. They’re using podcasts, the web, and a number of other tools. Part of what’s needed, says Allyn, is to implement software that coordinates the bits of content used.

• A new solution for content orchestration (sequencing of content, e.g. based on how the learner performs).
• Integration of training with policy or technical documents. Also integration of data for learning and non-learning purposes, and integration of social learning content.
• Integration with HR, SIS and enterprise standards (so that we know what type of learning the person needs, to do the job required).
• Incorporation of competency models.
• Support for new pedagogies (such as collaboration).

So a new infrastructure model may have a set of “resources” that are data stores such as published content, user information systems, competency store, and so on. Users will access the stores via portal interfaces and portal applications. It’s the mash-up idea. There will also be an external integration layer, to allow access to external content sources.

Open educational resources

We must differentiate between “open education” and “open educational resources”:

• “Open education” is the provision of educational experiences with few, if any, barriers to participation and often no cost.
• “Open educational resources” (OERs) are resources that can be used in learning under some form of open licence governing usage and adaptation. So you can include the open courseware into your learning system.

OERs improve access to educational content, e.g. in third-world countries like Africa. The aim is to reduce cost (text books are very expensive) and to improve quality (by pooling the knowledge of experts and taking the content that’s most relevant to your environment). This can be bad news to publishers of learning materials.

OERs are built to be reused, so that you can adapt and remix them to suit your needs. So it’s very interesting to look at OERs to see what’s happening with open learning at the moment.

Allyn emphasised that we need to have a structured content model in learning content, to support granularity (essential for content reuse) and interoperability (essential for mixing content).

One big problem at the moment is the editing and aggregation tools available. Allyn has used and reviewed a number of tools and has not found a satisfactory one yet.

XML is the appropriate format to support content and structure, ignoring presentation. Useful formats are CNXML (an open education resource format), DITA and others.

What can you do?

Next steps, particularly when considering co-operation between creators of technical documentation and creators of learning materials:

• Participate in common activities (e.g. LETSI).
• Be aware that your content may be used in ways and places you don’t know about.
• Write for broader reuse scenarios.
• Have a joint focus on reuse and interoperability.

Question time

Comment from the floor: “I don’t think it’s possible to re-use content. A lot of speakers at this conference have talked about it, but I don’t think it’s possible.”

Answer: Granularity is the key. Identify the content that is suitable for reuse. There’s no intention to reuse all content. When you write content in a narrative form, you are tied to writing in a particular way. But when you write structured, granular content, you’re not thinking about the presentation or where it’s going to be used. You concentrate on the content itself. That makes the content more reusable (where applicable).

Thank you Allyn for a very interesting presentation.

This week I’m attending the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. Today, the first day of the conference, the speakers have already given us a lot to think about.

Here are some notes I took from the session on structured authoring by Dave Gash of HyperTrain dot Com. I hope these notes are useful to people who couldn’t be at the conference this year. The AODC organisers will also publish the session slides and supplementary material once the conference is over.

A Painless Introduction to Structured Authoring

In this session Dave Gash discussed the benefits and pitfalls of structured authoring as opposed to the more traditional linear narrative format. He also touched briefly on DITA as the prime technology for a structured authoring environment.

When introducing Dave, Tony Self said, “Dave is known for his shirts, and he hasn’t let us down today.” Dave was wearing a black shirt imprinted with colourful guitars of all sorts. This set the tone for Dave’s live-wire style of presentation. He moved around the stage, chatting to and taunting people in the audience, while at the same time conveying lots of information.

Dave’s session covered the following points: “Look at paradigm shift from linear narratives to structured authoring. Compare and contrast the two methods. Explore structured authoring methodology. Look at some code examples.” He laughed, “This is the one and only time I’m going to use that phrase ‘paradigm shift’. I hate that phrase but it’s appropriate in this case.”

Here’s a good definition of structured authoring:

“Structured writing is a set of publishing workflow practices that lets you define and enforce consistent information structure and facilitates content development, sharing and reuse.”

We need to differentiate between structured authoring (the methodology we use to organise and structure information) and XML (the technology we use to implement the plan).

These are some of the problems Dave mentioned concerning the linear narrative format:

• There’s too much repetition, rewriting, local formatting. Not enough content re-use.
• Authors spend too much time doing things that are not writing, but are required for production of the documentation.

He listed the advantages that structured authoring can provide, including:

• Better control over content versions.
• More efficient use of a writer’s time.
• Easier sharing of content across different media and different formats.
• And more. Take a look at Dave’s presentation slides when the AODC makes them available.

Contrasting linear versus structured authoring, in linear content authoring:

• Content is authored in a WYSIWYG editing tool.
• Loose standards allow tweaking.
• Structure depends largely on output medium.
• Content and format are intertwined.
• Re-use of content is done via copy and paste.

On the other hand, in structured authoring:

• Content is authored in a WYSIOO (What You See is One Option) editing tool.
• Strict standards do not allow tweaking.
• Structure is completely independent of output.
• Authors cannot determine final appearance —  content and format are separate.
• Re-use of content is accomplished via cross-references.

To sum it up: The goal is valid content (structured) instead of attractive output (linear).

There are a number of benefits on the corporate and management side, such as improved document quality, content re-use, higher author productivity, more flexibility for varied output devices. In a nutshell: savings in personnel, software, support and maintenance costs.

For the writer/author, there are benefits and challenges. On the one hand, there are new tools and new procedures to learn, new job responsibilities that are narrower and less flexible than before, no control over formatting and publishing of the documentation. On the positive side, the change will keep your skill set current. Content is still king and you get more time to write it. No more copy and paste, and no more chasing around to find all the repetitions if you have to change something.

Dave also said you can throw away your responsibilities for formatting and publishing the documentation. As content developer, you are responsible for the content only. So if something breaks, it’s not your problem. I have to admit that I disagree with this point I guess that I enjoy the “holistic” approach to document production, where the writer does have a say in the presentation. So if my team was to move towards structured authoring, I’d definitely train myself up on the structure and publishing side as well as the content development skills. But I do recognise the need for content to be able to squeeze into all sorts of output formats and media. So I see the benefits of content being format- and medium-agnostic. I guess I’d fit into a structured authoring environment quite easily, once I started getting my sense of satisfaction from producing perfect content in an efficient environment.

Next, Dave showed us some code examples of HTML (representational markup) as opposed to XML (semantic markup). He explained how in linear authoring, the typography of a document defines its information structure while in structured authoring the tags define the information structure.

Dave gave us a real-world example: A technical writer writes a feature list, showing the set of features provided by a particular piece of software. This feature list might end up as an introduction to a user guide, as marketing literature, in a press release, in a software review site fact sheet, etc. It looks different in each output format, but it’s written only once.

Now Dave dived into the technical details of XML, the technology most used to implement structured authoring. He explained what a schema is and showed us some schema code. The schema controls what the editor allows you to enter. The editor checks against the scheme to validate the content you enter.

Dave showed us the workflow when using a linear narrative, and contrasted it with a structured authoring workflow. In linear authoring, the writer writes the content into a single tool, maybe interacting with a CMS. Then the writer instructs the tool to publish the content into different formats. In a structured authoring workflow, the writer writes the content into the editing tool, very likely working with a CMS. Then the information architect uses a structure tool and a style tool to structure the content. Then the publisher uses a tool to combine the style, structure and content to produce the different output formats. So there are more clearly defined roles and job responsibilities.

In structured authoring, information chunking becomes vital. Technical writers already chunk information i.e. divide it into logical pieces. For structured authoring:

• Think in smaller chunks.
• Consider where the information may be re-used.

Now Dave touched on DITA, the most successful XML standard for structured authoring. The DITA Open Toolkit is free, and there are a number of free plugins to extend the toolkit. For example, there’s the GUI publishing interface, WinANT, developed by Tony Self.

There are a number of authoring/publishing tools. Dave’s favourites are:

• JustSystems XMetal
• PixWare XMLMind Editor
• OxygenXML <oXygen/>

Other well-known tools are starting to support DITA to a certain extent:

• FrameMaker
• RoboHelp
• Flare
• Author-IT

The question time at the end of the session prompted a number of interesting comments, including these:

• Emily observed that the publishing and structuring side of document production may not be a full-time job, especially in smaller shops. So it may be quite possible for one person to fill all three roles — content author, information architect and publisher.
• How long does it take to move to a structured authoring environment? The answer depends on a lot of things, such as the amount of legacy documentation that needs converting and the level of enthusiasm in the existing team. There are a number of places in the States that have taken a year or more to get the first project out the door, and that’s without converting the existing documentation.
• With content re-use over multiple output formats, is there a danger of having the different output formats looking too much the same? Answer: Yes, there is a danger. It’s up to the formatting people to decide whether they want the content to look the same or different in the different locations.

Thank you Dave for a great introduction to structured authoring.

K15t Software have just announced release 1.0 of Scroll, a Confluence plugin that converts wiki documentation to DocBook and PDF. I’ve been interested in this project since the early beta days and I’m excited for the K15t guys about the functionality Scroll offers already and about their plans for even more awesome developments.

First things first: You’re probably wondering why they’re called “K15t Software” It’s because one of the developers and company founders is Stefan Kleineikenscheidt. I guess that most people, like me, go cross-eyed upon encountering his surname. So he uses “K15t”, in the proud tradition of “i18n” and other such abbreviations. Another K15t Software developer is Tobias Anstett, fondly known as “t11t”. During Scroll’s beta period we’ve had some good conversations via Twitter, blogs, video conferencing and email.

History in the making

The guys founded K15t Software as a company just a few weeks ago. If you’re a technical writer, you’ll like their mission statement:

“K15t Software is a small development shop from Stuttgart, Germany. Its mission is to build useful software products with the focus on tools for wiki-based documentation.”

It all started five years ago, when Stefan lodged a request for a DocBook export from Confluence wiki. The request is on the Atlassian JIRA site — CONF-762. A DocBook exporter is not on the roadmap for core Confluence, so Stefan and the team decided to build one as a plugin. And the rest is history! Well, it’s the future too, because K15t plan to keep adding features to Scroll.

How does Scroll work?

It’s a plugin (add-on) to Confluence. If you have administrator permissions on your Confluence site, you can install the plugin as described in the Scroll Installation Guide.

Once it’s installed, the “Scroll Wiki Exporter” option will appear in your Confluence menu. Here’s a screenshot of the option in Confluence 2.10. I’m on a wiki page called the “Crowd User Guide” and have opened the “Tools” menu on the right:

Scroll converts wiki to DocBook and PDF

When you choose the “Scroll Wiki Exporter” option, you get a screen with some tabs where you can choose either PDF or DocBook output and set some formatting options. On the “Document Information” tab you can set the document title, author and version. Scroll will provide default values based on the wiki page, but you can change them:

Scroll converts wiki to DocBook and PDF

The “Page Tree” tab shows you a hierarchical view of the pages you are about to export. The top level of the tree is always the page you were on when you clicked the “Scroll Wiki Exporter” option. The export will include that page plus all its sub-pages and their sub-pages etc. At the moment, “Page Tree” tab is view only. Scroll may allow re-ordering in a future release.

Next is the “Formatting” tab. Here’s where you choose either PDF or DocBook. If you choose PDF, you can select a theme, language, etc. Scroll 1.0 has two themes available. In future releases, K15t Software plan to provide more themes and also more options for customisation.

Scroll converts wiki to DocBook and PDF

The Scroll documentation tells you more about the formatting options.

On the “Advanced” tab, you can tell Scroll what to do if it encounters some wiki markup or macros that it doesn’t recognise.

Scroll exports wiki to DocBook and PDF

When you’re ready, you kick off the export. Scroll will show its progress and then present you with a file for downloading.

Scroll exports wiki to DocBook and PDF

If you chose to export as PDF, the output will be a PDF file. If you chose DocBook, it will be a zip file containing the DocBook 5 XML and all images and other attachments.

Some comments from me

I’ve really enjoyed my contact with Tobias and K15t. They’re passionate about their software, passionate about Confluence wiki, and keen to hear feedback. Here are some useful titbits from my experimenting with Scroll:

• Note the {scroll-ignore} macro. You can put it onto your wiki page to tell Scroll not to export a particular chunk of text/content.
• Scroll supports a number of wiki markup elements and macros. The Scroll Authoring Guide tells you how to write your text for best Scroll results.
• Scroll exports DocBook version 5.0.
• The “Scroll Quick Help” tips on the right of the export screens (see above) are useful and concise.
• It’s really useful to be able to determine error handling, telling Scroll what to do when it encounters some wiki markup or a macro that it doesn’t know what to do with. See the “Advanced” tab described above.
• In the PDF export, the “Simple Documentation” theme is neat and attractive.
• For PDF, Scroll 1.0 has two themes available. In future releases, K15t Software plan to provide more themes and also more options for customisation. They’re also planning to allow pluggable themes, so that developers can create their own themes for Scroll.
• I’ve suggested an addition to the Scroll documentation, to provide more information about the DocBook XML produced. The Scroll team have added this to their “to do” list.
• The section on nesting of headings in the Scroll documentation explains why your heading levels may sometimes be different to what you expect.

Some comments from Giles

Giles Gaskell is a technical writer and colleague at Atlassian. He’s had extensive experience with DocBook, so he’s very interested in the Scroll plugin for Confluence too and I’ve been delighted to have his help with the plugin analysis. Here are Giles’s comments:

• I really like the XML indenting that Scroll generates. It makes the XML output very readable via a standard text editor. I’ve worked with several XML editors in the past that force you to use their products to read/edit your XML content, since they either implement their own strange XML indenting or remove all white space > 1 character in length, in their XML output files.
• It’s great that the version of DocBook XML exported by Scroll is 5.0. There are several processing advantages in DocBook XML 5.0 (via the RELAX NG schema) over what’s available in previous versions of DocBook XML (which are based on DTD schema only). Furthermore, it seems that RELAX NG is the way DocBook XML processing is headed.
• I validated both DocBook XML exports using my own installation of jEdit and both were without any errors
• Scroll does not add a document type declaration at the top of the XML output. It seems that DocBook XML 5.0 files which make use of RELAX NG-based processors typically do not possess a document type declaration. Likewise, it seems that DocBook XML 5.0 output without a document type declaration can only be processed by tools which are RELAX NG-compliant. Hence, it might be useful to have an option in the Scroll Wiki Exporter to add a document type declaration to the XML output, so that XML processing tools which verify XML against DTDs only can process these exports. [Giles would be very interested to hear any comments on this point from other DocBook users.]
• It might also be worth providing an option to choose the version of DocBook XML exported — 4.0, 4.5 or 5.0. However, k15t might consider conducting a brief feasibility study on this first as I suspect integrating this feature would require a fair bit of work and some understanding about the differences between each version of DocBook. The main area of demand for this feature would be customers who have an existing/legacy tool setup that manipulates DocBook XML 4.x content, but do not have resources to upgrade their entire system to DocBook XML 5.0. DocBook XML 5.0 was only officially released in January 2008, so I suspect many DocBook XML customers would still be using DocBook XML 4.x.
• Regarding the use of the <article> root element as opposed to <book> in the DocBook XML output: I believe this is an advantage, as it gives the author more flexibility to structure their books. The <book> element encapsulates information about a book’s content at a higher level than what is contained within an <article>. For example, an author may want to export multiple DocBook <article>s from a Confluence installation. These might be sourced from a variety of Confluence spaces or subtrees. They might then wish to combine these exported DocBook XML <article>s into a single DocBook <book>, using their own DocBook XML editor. If Scroll exported to a DocBook <book>, this would not be possible without additional XML processing.

Giles is also discussing a couple of minor points about the DocBook XML, such as the fact that each <link> element defines its own xlink namespace, and the production of the <?linebreak?> processing instructions.

Try it out yourself

You can either download the plugin for evaluation from the K15t Software site and try it on your own Confluence wiki, or you can use their demo Confluence site to see the pages already there, create your own pages, and then export them to DocBook or PDF. Awesome!

That’s all folks

Both Giles and I enjoy working with the K15t Software guys. They’re very quick to respond to feedback and I’m sure they’d be delighted for more input from other technical writers.

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