Today I received the stunning news that the DocTrain conference series is no more. PUBSNET, Inc., the company behind the series, is going out of business. This summer’s DocTrain DITA conference has been canceled.

I am stunned and saddened. Our industry has lost one of its best educational events. DocTrain conferences offered sessions on forward-looking topics, focused on advanced practice but offering multiple levels of learning.

The conference cost even included pre- and post-conference training. The first and last days featured morning and afternoon hands-on workshops with engaging topics and speakers.

I am grateful to have been a volunteer staffer at DocTrain East 2007 and 2008 and at DocTrain West 2009. I am especially grateful to conference director Scott Abel of The Content Wrangler and Eileen Savary of PUBSNET for giving me the opportunity to work with them. I made valuable business connections. I made rich, enduring friendships. I learned more than I can convey.

The demise of DocTrain is an example of how the economy is affecting our precious learning resources. In an article that I have recommended at the end of this post, Scott Abel gives the big picture on the state of conferences and trade shows. He also offers some encouraging news about free online learning events coming this summer.

I welcome your comments about how cutbacks have affected your learning opportunities. How are you filling the gaps? What online learning communities are you finding useful?

Related posts

To get the full story about the death of DocTrain, read Scott Abel’s article on the Content Wrangler site.

For the perspective of a DocTrain presenter, read Thoughts on DocTrain by Scott Nesbitt of DMN Communications.

Days have whirled by since I returned from the west coast on April 5th. I had planned to write posts about both of the conferences that I attended while I was away, but I have been consumed with a new project, a condo purchase, and moving logistics.

For information about DocTrain West 2009, see these posts:

• Read about the Firefox book sprint
• Read about DocTrain West 2009 sessions that I attended

This post focuses on the WritersUA 2009 Conference for Software User Assistance, held this year in Seattle. In case you are unfamiliar with WritersUA (formerly WinWriters) or have never attended a WritersUA conference, I encourage you to do all of these things:

• Visit the WritersUA site
• Join the WritersUA email list
• Learn more about WritersUA conferences and plan to attend next year’s conference

The 2009 Conference Setting

The WritersUA organization is based in the Pacific Northwest (my favorite part of the US), so their annual US conference is usually held on the west coast. Last year’s conference was in Portland (Oregon), and this year’s was in Seattle.

When I attend conferences, I like to arrive at least a day early for pre-conference sessions. I also like to get out and explore the city where the conference is being held. I had previously been to Seattle during summer, so I hadn’t experienced its characteristically chilly, rainy weather. But I have explored Portland, Paris, and London in rainy weather, so I made the best of it.

Since this was my second visit to Seattle, I didn’t visit any tourist attractions. I had seen most of the major sites on a previous visit. This time I simply wanted to enjoy the city’s ambiance. I visited the waterfront, but other than attending the conference I mostly enjoyed various Seattle restaurants and shopping with others who were attending the conference. I had dinner with MadCap CEO Anthony Olivier and Vice President of Product Development Mike Hamilton. I went on a pub crawl organized by several Australian conference attendees. And I had a lot of fun discovering places in the city with my friend and colleague, Lauren Anthone.

The conference was held at the Westin Seattle, and I stayed on the 42nd floor. The view and the perspective of weather were fantastic. At one point, I could see a heavy snowfall from my room. I called Lauren, who was waiting to meet me at street level. I asked what she thought of the snow. She was seeing only rain, so the snow never made it to the ground.

Some say that I was hallucinating. I’m not mad! It was snowing, I tell you!

Conference Sessions

Some of the sessions that I attended were related to tools such as Flare and XMetal. I also spent a day at the vendor expo, working with my MadCap colleagues. I had the opportunity to talk with existing and prospective MadCap customers.

I attended the following sessions related to methodologies and best practices.

Introduction to DITA (Tony Self, Pre-conference)

Right now, the hottest topics in our industry seem to be social media and the Darwin Information Typing Architecture, or DITA. So as we move toward collaborative work environments, we’re also moving toward more structured writing.

Although I have attended a class or two on DITA-enabled tools, extensively studied the DITA architecture, and created DITA content, I had never had formal, tool-independent training on the DITA standard. A three-hour, interactive DITA course led by Tony Self was just what I needed. Tony is one of the founders of HyperWrite in Melbourne, Australia.

Tony made a solid case for DITA adoption, including its strengths as an efficient, automated methodology for content reuse and single sourcing. He covered the basics of structured, modular writing, included an XML refresher, and led us through the specifics of DITA content creation.

We also discussed project and process planning for DITA implementation. Like content planning for any project, DITA requires modeling and information typing. You especially need to determine whether the basic information types (concept, task, and reference) are sufficient for your needs or whether you need to specialize.

DITA requires paradigm shifts. For example, in traditional help authoring, we create linked topic relationships using various methods. In Flare I sometimes assemble pre-determined Related Topics lists. More often I create a list of concepts, insert concept markers in topics, and let Flare build dynamic lists based on concept relationships (See Also lists). Tony pointed out that when you create DITA content, you should avoid linking because it adds context. DITA is designed for truly modular, standalone pieces of content, so relationship tables control the linking aspect behind the scenes. This puzzles developers who are used to traditional ways of controlling the linked structure, so it may take some mental adjustment.

Tony Self is a leading industry expert and an engaging instructor. He’s also a great person. I came to know him in a separate context when I attended a pub crawl organized by Australian conference attendees. Now I picture him draped in the Australian flag and leading us in the “Aussie, Aussie, Aussie” cheer.

The Google Chrome Comic and Visual Communication
(Scott McCloud, Keynote)

I am a fan of comic books as a learning tool. Apparently Google shares my enthusiasm.

The opening conference session featured Scott McCloud, author of Understanding Comics. Scott describes himself this way:

Depending on who you ask, I’m either comics’ leading theorist or a deranged lunatic…

In an interview with WritersUA President Joe Welinske, Scott talked about the process of creating the comic book that describes the technical aspects of the Google Chrome browser. He also discussed how comics offer an alternative way to tell a story, even in a business context.

When friend and colleague Carolyn Kelley Klinger and I began working together at the National Cancer Institute, our projects involved software applications that supported genetics research and terminology. Carolyn asked SMEs for a book that was accessible to non-geneticists, and they wholeheartedly recommended The Cartoon Guide to Genetics by Larry Gonick. I came to appreciate this mode of learning and became addicted to the rest of Gonick’s Cartoon Guides. Those guides are a great way to learn complex, scientific subjects. I now have a collection of them.

User-Centered Design of Context-Sensitive Help (Matthew Ellison)

When I use software and expect to find useful, context-sensitive help (CSH), I often find that the result is perfunctory at best. Although my software utopia prominently features embedded help, I realize that CSH, when used effectively, can be a user’s best friend.

Matt Ellison traced the history of CSH from WinHelp to the Office 2007 ribbon and super tooltips. He provided varied usage examples, past and present.

One of the better examples (in my opinion) of a CSH landing page included these elements:

• method of access
• overview of the window’s purpose
• conceptual information supporting usage
• specific window features and how they’re used
• links to related topics

Matt emphasized that, regardless of what we include in CSH topics, we need to keep the user in the task flow. As he pointed out, users typically consult the help when they are already engaged in a task. Thus, CSH should provide “quick and easy answers to mid-task questions.”

Here’s the first list expressed as questions:

• How do I open this window?
• What’s the purpose of this window?
• What do I need to enter in this field?
• Why do I need to provide this information?
• What does this feature do?
• Where can I find more information?

Matt provided many examples of varied approaches, showing how we sometimes provide too much or too little information, rather than giving users exactly what they need at the moment they seek help. He suggested that CSH topics should enhance task performance with a combination of conceptual and reference information, rather than procedural. One of his key points is that we should “focus on answering likely questions rather than documenting the application.”

Architecting UA Topics for Reuse (Michael Hughes)

Although savvy doc teams have established methods of reusing content for years, a lot of cutting and pasting is still going on. I see this first-hand when I work with new clients, and I try to steer them toward modeling and analysis for reuse. I have used various tools and techniques over the years to implement and support reuse, so I am now learning about how DITA supports reuse.

This session by Mike Hughes was a useful extension of Tony Self’s pre-conference workshop. But even though Mike used DITA examples, the principles he discussed are applicable to any development environment.

After providing an overview of content reuse and its benefits, Mike provided examples of reuse in different media and different documents. I appreciated his emphasis on using semantic markup to separate content from presentation. DITA, for example, uses uicontrol in lieu of strong to bold UI elements.

Mike says

Don’t tell me what it should look like. Tell me what it is.

Mike also reinforced Tony Self’s point about linking topics, saying that we should “avoid embedded links that create dependencies.” To achieve truly modular reuse, we need to separate content, structure, and relationships.

Techniques for Reviewing a User Interface (Rhonda Bracey)

As writers of documentation for software products, we often work with a variety of user interfaces. Well-designed interfaces make our job easy. Others make it downright difficult. How many times have you searched for euphemisms to describe software “features”? How often have you struggled with procedural steps that became needlessly complex because you were forced to explain UI elements that were not intuitive?

I have often worked with software development teams to provide usability input and suggestions for improving a user interface. I usually create a spreadsheet report that is tailored to evaluating the application. Rhonda Bracey, owner of CyberText Consulting, has done better. She has developed a useful checklist that gives us a repeatable evaluation strategy.

For starters, Rhonda reminded us that our words aren’t the only thing that should communicate. She quoted a post from Chuck Martin on the Help Authoring Tools and Techniques (HATT) group from January 2008:

‘Communication’ encompasses not only the words created for manuals and help systems, and not even the words used in the interface, but the interface itself, and the way it does—or doesn’t—inherently communicate its functionality.

Rhonda recommended that a tech comm professional start evaluating the interface early in the development cycle. We should check for clarity, consistency, and conciseness, while helping to reduce confusion. This includes the following categories:

• Design elements: Are interface elements well placed? Do they contribute to the overall flow?
• Text elements: Are labeling and wording consistent in such things as title bars, status bars, menus, icons, buttons, and system messages?
• Link elements: Do link mechanisms such as menus, sidebars, breadcrumb trails, and URLs work?
• Visual elements: Is the design coherent, or do some elements have a jarring effect?
• User actions: When you interact with a UI element, is the result what you expected?
• Performance: Do you spend a lot of time waiting for a system response?

Rhonda provided suggestions for tools that aid the process of UI evaluation, but she reminded us that the eyes and brain are our best tools.

• Read Rhonda’s related article in UX Matters
• Download Rhonda’s checklist (PDF) or buy an editable version here

Back to top

I am back in the DC area after nearly three weeks on the west coast and a couple of days in Atlanta. This was my agenda:

• Attend the DocTrain West conference in Rancho Mirage, CA
• Spend a week with friends in the San Diego area
• Visit MadCap Software headquarters in La Jolla
• Attend the WritersUA conference in Seattle, WA
• Attend and sing at a wedding in Marietta, GA

Since the trip was a bit of a marathon, I had tried to be budget-conscious in planning it. Counting layovers, I visited seven different airports. I endured crowded, overbooked flights. I pondered the mythical concept of preferred seating.

Despite our economic woes, lots of Americans are traveling. I’m happy to be home.

Nevertheless, the conferences energized my mind and filled my head with ideas. I always return from conferences with long to-do lists and a larger tag cloud on Delicious.com.

DocTrain West 2009 was held at the beautiful Westin Mission Hills resort in Rancho Mirage, California, just next door to Palm Springs. The big attraction of the resort is its golf course, so the juxtaposition of greenery and desert terrain is strangely exotic and beautiful.

Firefox Book Sprint

During the first two days, I participated in a Firefox book sprint, where a group of writers wrote, edited, and published a manual for the Firefox browser in two days. To read more about my experience as a participating writer, see my March 27, 2009 post.

Summary of DocTrain Sessions

Since I participated in a two-day book sprint and served as a conference volunteer, I mainly attended sessions on the second full day and final (post-conference) day. This section describes the sessions that I attended.

David Esrati on Mass Marketing and Social Media

Keynote speaker David Esrati gave a provacative presentation titled The Content Providers Crystal Ball: What Everybody Missed During the Digital Revolution. Esrati traced the evolution of mass marketing from commercial spots supporting 1940s serialized radio dramas to today’s free web services. He pointed out that “free is the new currency.” With the proliferation of so many free services, competition among businesses is more fierce than ever. No matter how great your company’s content is, you have to build solid relationships with your audience to entice them to consume it.

Esrati asserted that print newspapers are essentially dead. For the most part, I agree, though some family members and friends still love the tactile experience of newsprint. I get my news delivered to my email inbox, from which I can link to stories on The Washington Post and The New York Times sites. I especially love the Times site and believe that it’s a great example of how print publishing can adapt to new media.

Sarah O’Keefe on the State of DITA Publishing

Sarah O’Keefe, President of Scriptorium Publishing, shared her findings on three major options for publishing DITA content to PDF. In a presentation titled Demystifying DITA to PDF Publishing, Sarah weighed the pros and cons of the three solutions:

• For publishers who want to achieve the best design and typography, Sarah recommended a layout tool such as Adobe InDesign. The caveat is that InDesign requires extensive configuration for XML publishing.
• The DITA Open Toolkit is the best solution for automated publishing, though it offers little control over page layout. It’s also challenging to set up and troubleshoot.
• As a happy medium, Sarah recommended Adobe FrameMaker. While FrameMaker also has limitations, it does a great job of publishing PDF and allows control over page layout.

Ann Rockley on Intelligent Content

In a presentation titled Making Content Intelligent, Ann Rockley focused on making content “discoverable, reusable, reconfigurable and adaptable.” Because I have worked with ontologists using a semantically constructed OWL database tool for the last couple of years, I was especially interested in Rockley’s idea that content can be “semantically aware” and “adaptable.” As I see it, the adaptability of content is not only key to effective content management; it’s also key to the realization of a truly semantic web.

Pam Kostur on Content Reuse and Modeling

Continuing along the path of content reuse and management, I attended two post-conference sessions by Pam Kostur of Parallax Communications:

• Writing Modular Content: Making Content Behave focused on modular, structured writing.
• Building Content Models: Constructing with Content focused on analyzing content and building a model from it.

Pam gave us some policy material to analyze and consolidate. The examples were challenging and emphasized how content analysis can be similar to solving a puzzle. One attendee expressed a need for Advil.

Sarah O’Keefe on Gutenberg and XML

Sarah O’Keefe returned for the closing keynote presentation, What Gutenberg Can Teach Us About XML. She first traced the history of publishing from hand-crafted books through the introduction of Gutenberg’s printing press. The early mechanization enabled more widespread dissemination of published content but reduced the aesthetic value.

In a similar way, XML forces writers to focus on structure and content and less on beautiful presentation. This can be a tough adjustment for writers who have thrived on desktop publishing. I have been a style sheet developer for years using various proprietary tools and CSS, but I have little trouble adapting to XML authoring. I love the simplicity and the purity of structured writing.

I always enjoy Sarah’s presentations, because she’s gifted at delivering the most technical subject matter with clarity, wit, and wisdom. Here are relevant links for both of her presentations that I have covered in this post:

• View Sarah’s DITA publishing presentation on Slideshare.com
• Download and read Sarah’s Gutenberg article

[Backtotop]

In my last post, I expressed my admiration for wikis as a collaborative solution for project and process management. I didn’t discuss wikis as a publishing platform for technical documentation, simply because my clients haven’t yet taken that step.

Fellow blogger Jason Coleman expressed his views on wiki-based tech docs in a comment following my post. In my response, I promised to report back after participating in the Firefox book sprint at DocTrain West 2009.

Having seen a demo of the FLOSS Manuals site last fall, I had been looking forward to the Firefox book sprint with eagerness and curiosity. I had never participated in a real-time, collaborative writing event of that magnitude. So on March 16 and 17, I joined several writers in a conference room in Rancho Mirage, with other writers participating remotely from other US states and other countries. Our goal was to produce and publish a manual for the Firefox browser in two days.

After participating in the book sprint and using the FLOSS Manuals TWiki publishing platform, I am now a wiki publishing convert. Granted, a true, complete publishing solution takes quite a bit of customized development, but the FLOSS Manuals platform exemplifies the possibilities.

The FLOSS platform encourages topic-based writing. It has a simple user interface for writing and editing. It enables participating writers to remain aware of the status of big-picture content development at all times. As a participant, you can chat with remote writers. You can observe the state of in-process topics (such as needs updating, to be proofed, or complete). You can save your work and resume later, or another writer can step in and complete the topic.

We used Firefox help topics as source material, with the goal of improving the structure and the content. We wrote. We edited. We held group discussions. We had direct access to Firefox expert Chis Hoffman of the Mozilla Foundation. Chris was on site with us in Rancho Mirage.

At the end of the sprint, we all gathered to watch as FLOSS founder Adam Hyde walked us through the publishing process. Seeing the result of our work published in real time was exciting. The platform does an amazing job of paginating, and it includes headers, footers, and page numbering. It also enables you to “remix” a book’s content and publish your own customized version. You can buy published FLOSS books from the FLOSS Manuals storefront at lulu.com. The proceeds help to further the work of the foundation.

Here’s a picture of some the writers who participated on site at Rancho Mirage.

Left to Right: Adam Hyde, Me, Greg Urban, Jay Maechtlen, Chris Hoffman, and Janet Swisher (Photo courtesy of Greg Urban)

Remember, you can participate in a FLOSS Manuals book sprint without attending in person. You can join as a remote participant. By helping to create documentation for free, open-source software, you can help encourage more people to use the software. If you are interested in participating in future sprints, you need to register on the FLOSS Manuals site.

Fellow blogger, tech comm expert, and FLOSS Manuals evangelist Anne Gentle expresses exactly why I found the sprint so amazing:

A book in two days thanks to a great group of writers, an excellent Subject Matter Expert, and remote contributors from Calgary to Moscow to Bangalore.

You can visit Anne’s blog to read her full summary of the event. Then join FLOSS Manuals and have some fun.

Back to top

For the last 2.5 years, I have had the honor of developing content that supports cancer research. I developed various guides, online help, and a training course for the National Cancer Institute Center for Biomedical Informatics and Information Technology (NCI CBIIT). My audiences included ontology editors, software developers, administrators, and grant managers.

I found my work with the Enterprise Vocabulary Services (EVS) group especially rewarding. The EVS is a subset of NCI CBIIT. The primary mission of the EVS is to “harmonize and integrate the many diverse terminologies and coding frameworks used by the NCI and its partners.” The group works with research institutions in and outside of the United States to promote collaborative terminology development. Their technical infrastructure includes the NCI Thesaurus and other terminology databases. My work supported the development and maintenance of that infrastructure.

The EVS also introduced me to the world of wikis. If you have no idea what a wiki is, you can learn more about wikis at Wikipedia.

Make Wiki, Not War

Before working at the NCI, I had no direct experience with wikis. The software developers at a previous job had set up a wiki using the “build it and they will come” principal, but no one led the effort. The wiki eventually languished.

I had also come close to working on a wiki-based project while consulting with a large service organization to develop a centralized knowledge base. Various factions were at odds about whether to use a proprietary database or an open-source wiki solution. A particularly influential business unit was lobbying to deploy the wiki, but the management team was against it. Management was wedded to their solution and made no effort to understand wiki technology. They simply asked me to step in and explain to the sub-group why a wiki wasn’t appropriate.

Because I had so little knowledge of wikis, I wanted to do research before getting involved in the discussion. I asked “shouldn’t we all become more educated on the subject of wikis before we dismiss the idea?” But the managers wouldn’t hear of it. They had heard too many stories about wiki anarchy and loss of control. Ironically, after doing the research, I was convinced that a wiki might be a better choice than the proprietary solution. After failing to change the minds of the naysayers, I managed to extricate myself from the political crossfire.

The Wisdom of Wiki-Building

The NCI CBIIT experience gave me my first real opportunity to develop content in a wiki environment. In early 2008, the organization implemented a wiki for project management, process management, and resource sharing. Long-time STC member and wiki expert Ann Wiley was the site architect and mentor. In addition to other daunting tasks, she built an online catalog of our sizable documentation library.

I began to appreciate the power of wikis as a versatile tool for organization and knowledge sharing. I could see daily details of projects to come. I could instantly post a live information plan, share it, receive notification of comments, and update it. No more circulating Word documents and waiting for review comments. The wiki gave new meaning to the concept of a “living” document.

Later in the year, the EVS launched the BiomedGT wiki to support the development of the Biomedical Grid Terminology, “an open, collaboratively developed terminology for translational research.” The wiki promotes collaboration from terminology experts in the scientific community, though it’s hardly the renegade monster that my other clients feared. Anyone can browse and search the terminology, but they cannot create a login or edit the terminology without first undergoing a screening process. Interested collaborators must submit their contact information and credentials, be approved, and receive a login from the wiki administrator.

Even after passing the screening process, approved BiomedGT wiki collaborators cannot directly edit the terminology. Instead, they suggest changes by submitting “proposals” using online forms. Those changes can range from retreeing a term (moving it to another position in the hierarchy) to deprecating a term.

At the point of submission, a proposal enters a workflow process where it interfaces with internal NCI editing tools. The most notable of those tools is NCI Protégé, a version of the open-source, OWL-based Protégé ontology editor developed by Stanford Medical Informatics. While NCI editors review the proposals and “curate” the vocabulary, outside collaborators can use the wiki to trace the proposal status.

I contributed to the BiomedGT wiki by editing and restructuring information, writing help pages, and adding CSS flourishes. I found the work liberating, because the focus was mostly on writing and content. Wiki markup is easy to learn, and wiki templates are a great mechanism for content reuse.

Wiki out West

Next week brings a new wiki adventure. While attending DocTrain West in Palm Springs, I will participate in an event called Firefox Book Sprint: From Zero to Book in Two Days. We will use the FLOSS Manuals toolkit, a collaborative wiki writing environment, to create a new manual for the Firefox browser.

I first learned about FLOSS manuals and met its founder, Adam Hyde, at DocTrain East in October 2008. FLOSS Manuals is a not-for-profit, volunteer-based foundation based in Amsterdam. FLOSS stands for “Free, Libre, Open Source Software,” and its volunteer writers collaboratively write documentation for free, open-based software. FLOSS writers also wrote the help content for the One Laptop Per Child program. I am excited about the opportunity to be a part of a Book Sprint.

Related Links

This section provides links to everything that I have discussed in this post.

• Learn more about the NCICB
• Learn more about the EVS
• Visit the BiomedGT wiki
• Learn more about the Protégé ontology editor
• Visit the FLOSS Manuals site
• Learn more about the One Laptop per Child program
• Learn more about the Firefox Book Sprint at DocTrain West

Back to top