There are many reasons why Flash and even Adobe Air are not the best solution for delivering content. Mobile devices need stealthy, small footprint apps, and the Flash footprint is just too large to manage on mobile devices. And, search engines can’t index content in Flash or Adobe Air. Search engines cannot penetrate Flash content, and Air uses frame sets that cause indexing to fail. What good is comprehensive help content if users can’t find it on the Internet or access it from their tablets and smart phones?

Many help authors think that by putting their help systems on the Internet, or on a corporate Intranet or Extranet, they have made help topics available to users. Unfortunately, that is not the case.

Now that Amazon has released Fire, its new tablet that costs under $200, tablets are more accessible to more people and the market will continue to grow. With technology advances like this, readers will expect more from content delivery systems. They will want to use powerful search engines to fetch precise answers that can be found within the top search results. To make that possible, help authors need to understand what impedes devices from accessing content and search engines from indexing it. Authors also need to know how to use metadata and manage it to enhance search results, how translation can be managed for help topics, what types of help systems support these tasks, and how to convert from what they have now to something that is capable of delivering content when and where it is needed.

It is time to trade in CHMs, RoboHelp, MadCap Flare, Adobe Air, Eclipse Help, and some WebWorks Help in favor of systems built using straight HTML5, JavaScript, CSS, and other open technologies that can provide access to content from any device or search engine.

Don’t you find that when you don’t know how to get something done, the first thing you do is turn to the Internet and search for help?  That is what I do, and I get dang frustrated when I can’t find an answer that will get me up and running again quickly!

We had to face exactly this issue recently when TechProse was asked to build a new online help system.  On this project, we had inherited a very labor intensive process for creating help that involved FrameMaker and MadCap Flare.  It took four weeks to create the help and a lot of hand manipulation of the resulting MadCap Flare HTML outputs to get the typography we needed.  That was not going to be sustainable and we knew could find a better way.

In addition, one of the main requirements for the help was to  ensure that the topics would be accessible on the Internet. You might think that all we had to do was find a better pairing of authoring tool and help output,  and then put the resulting help system on the Internet.  That made logical sense to us too, until we got into researching the tools.

Most Help Systems are Closed

Much to our surprise, we quickly learned that CHMs, Robohelp, MadCap Flare, Adobe Air, Eclipse Help, and some WebWorks are not indexable by Internet search engines. Most of these help systems rely on framesets or iFrames and tables to control formatting and place text elements on the page. This causes search engine indexing to fail.

Some of these help systems rely on plugins, such as Flash or Flex, to display help topics. This requires that the device accessing the topics have the plugins installed and have the capability to run them. Not all companies allow users to install these plugins and not all devices can use them.

Eclipse help requires a service to be actively running on the web server. Occasionally, this service needs to be manually reset. While the service is inactive, help topics are not available.

Being Open

We found that all these issues can be resolved by using an straight forward HTML help system that does not rely on these technologies:

• Framesets/iFrames
• Tables for page formatting
• Plugins/Flash/Flex
• Services running on the web server

That is why TechProse selected HTML5 and DITA, managed by the DocZone CMS, to deliver our help output to the Internet. HTML5 is designed with search engine optimization and accessibility in mind. Further, DITA enabled us to reap the many benefits of single-sourcing and automated publishing. By switching from FrameMaker and MadCap Flare to DITA and HTML5 help, we reduced publishing costs by 15%, increased the quality of the user experience, and made help topics accessible from any Internet-capable device.

To add more velocity to our publishing process and help us manage the DTIA topics, we also went out shopping for a content management system (CMS). By choosing DocZone, a SaaS XML CMS, we were able to get the content management and publishing functionality we needed at half the cost of a traditional CMS.

Case Study

We will be showcasing the case study for this project at the 2011 Best Practices Conference in San Antonio, September 12-15.  On September 28th from 1-2 pm Eastern, you can attend a free webinar hosted by DocZone where we will present highlights from this case study.

Non-DITA Native

Authors coming from a FrameMaker or MS Word background are used to lots of things being transparent to them. They don’t think about these things because they’ve trained themselves how to get them done. For instance, FrameMaker gives you a report of unresolved links and often takes you right to the area where the broken links are so you can easily fix them. If you want to delete a condition you have set on some content, you can just remove the condition from the conditions list and Fame removes the condition from the content. If you don’t want to, you don’t have to worry about linking or reuse strategies or information models. Further, when using FrameMaker and MS Word, it is most common to author using a simple, uncomplicated linear book model, whereas DITA topic-based authoring allows authors to have very complex information models, mixing and matching topics in all sorts of fancy ways.

OMG

When FrameMaker or MS Word authors begin to retrain their conditioned minds to embrace and adopt DITA, they often experience a period of major angst! You know, that OMG shock of “I’ve a feeling we’re not in Kansas anymore!” When you first start authoring in DITA, although the writing of content is fairly straight forward and the style formatting is all automated, you have to learn how to tag the content. And, if you have never thought about reuse, conditionalizing, filtering, how to identify what should be a topic, how to find reusable topics in a CMS, then you might feel like you are trying to climb Everest while simultaneously keeping up with the release schedule!!

Dita Never Fails

In my experience, DITA technologies never fail. The machinery works and delivers as promised when properly configured according to well thought out business and functional requirements.

However, if the people who are using DITA systems are not properly set up for success, it is possible that they will struggle deeply and develop a resistant mindset that DITA is a failure.

Proper change management and training is essential when transitioning to a DITA system. So is maintenance of the system, enabling it to grow with its authors and users.

Paying experts to plunk down a starter DITA system and then leaving it to inexperienced DITA authors and users expecting them to get the most out of it, does not guarantee success.

DITA is an investment in mature and efficient content automation and management technologies, in training and growth for the people who use these technologies, and in a future that has proven over many years and implementations to deliver a substantial ROI along with an abundance of productivity and soft benefit gains.

Keys to Success

In a nut shell, my secret to success has been …

1. Provide proper change management, including early and ongoing communication with all effected team members. Make them part of the change process.
2. Set up the initial system according to well thought out business and functional requirements.
3.  Engage users of the system in Initial and ongoing training, providing experienced support as they work through their learning curve and growth with the system.
4. Plan for periodic reviews with adjustments of the systems, processes, and training to ensure that they are all producing the results you expected to get from the transition to DITA.

Do this, and you can make the effort of transitioning to new DITA technologies an exciting growth journey for all involved. And remember, when taking a growth journey, a playful attitude never hurt.

Happy authoring folks!!

Paula will be making a presentation at the STC Summit  entitled Change, Trust, Collaboration: Adapting to Single Source Technologies to share what she has learned. You can find this presentation in the in the Communication and Interpersonal Skills Track. If you are interested in leveraging your ability to adapt to single sourcing, drop by and see how you can applying this simple methodology to ensure the success of your single-source project.

http://www.softconference.com/stc/sessionDetail.asp?SID=232476

1. Factors that indicated the need for a new approach to corporate product documentation
2. Why single source was the solution selected
3. The RFP process
4. Challenges and opportunities
5. Processes and best practices
6. Lessons learned

Register here: http://stc.org/education/online-education/live-seminars/item/managing-major-corporate-change-two-perspectives?category_id=53

“What’s different this year?”

Gwaltney Mountford, East Bay Society for Technical Communication president launched into the chapter’s annual Trends Panel with this question for panelists Meryl Natchez, Linda Urban, Yas Etessam and Jeff Gardiner.

Since last year, the technical communications landscape has changed quite a bit, panelists said at the March 4 meeting in Danville, CA. Here’s an overview of the trends:

1. The good news is the job market has improved. However, while there are more jobs, they may be confusing to navigate because in many cases, technical communicators aren’t simply writers anymore. They have titles such as “Community Liaison” and “Content Curator.” In these roles, they provide content but they are also interacting with users and deciding which content is relevant to their audience.

2. Organizations are talking about the business value of editors. Yas Ettesam cited an IBM study that shows that edited pages are 30% more engaging to readers than unedited pages. Read more about the study here: http://writingfordigital.com/2010/07/04/a-fourth-of-july-lesson-in-the-value-of-editors/

3. In the past, technical communicators volunteered to monitor wikis and other customer-facing online documentation. Today, more organizations are seeing the value of hiring technical communicators to own this critical documentation. That means no more cramming the task of monitoring the wiki into your already busy schedule.

4. Our brains are changing! Jeff Gardiner discussed how the human brain changed when we went from an oral tradition to a printed tradition. Now that we are moving away from reading printed content to reading chunked, online content, our brains are changing again. (An interesting book on this subject: The Brain That Changes Itself, by Norman Doidge.) We have shorter attention spans. Enter Twitter, where users create 140-character tweets to communicate about everything under the sun. Linda Urban suggested that Twitter is a good way to “see bubbles of discussion.” It is not a bridge to mastery, she says, but it is a means for gaining awareness about many different topics. Technical communicators who aren’t familiar with Twitter or the ubiquitous hash tags need to jump on the bandwagon – now.  Try following areas of interest, or tweeting yourself. Jump into a public wiki to read or edit.

5. Shorter attention spans and an interest in reading chunked material means technical writers need to be training themselves to write in minimalist forms. They also need to be able to organize and categorize data and use meta data to help users search for what they need.

6. Historically, technical communicators have not been very good at selling their work as a corporate asset, Meryl Natchez said. But there are many ways to promote what you do. Natchez suggested technical communicators celebrate their achievements on the company Intranet, promote links that inform co-workers, and network at conferences and within their organizations. “You can’t just sit in your cubicle,” Natchez says. “You have to let people know what you’re doing and communicate your value to the organizations.”

Urban suggested that technical communicators actively look for ways to improve processes and the organization as a whole. When you suggest ideas, leaders see you as a problem solver, not just as a technical writer.

Etessam suggested technical communicators speak up and ask if they can participate in other areas that are relevant to their work. For example, don’t be afraid to ask if you can attend the design meeting. Exploring other areas of the business often provides insight that improves your practice and longevity in the organization.

Gardiner suggested technical communicators find out what their organization’s marketing people are talking about. What are the buzz words? What are the pain points in the organization? Be aware of trends in the organization and make suggestions that are in line with them.

Steven Laine, TechProse President

I’m interested in your thoughts as I ponder the future of publications and content within corporations: Does content need to be owned at a corporate, senior manager, maybe even C-level (as in CEO, CFO, CIO, etc.), rather than at a technical publications manager level to get the full strategic value out of the content?

Here is the background: I was at the Intelligent Content conference that Ann Rockley’s group put on earlier in February. It was a great conference, very targeted, intense and useful.

The concept of intelligent content is compelling, logical and so common sense – let’s find, capture and reuse our own stuff so we are more consistent, efficient and responsive across the entire organization from tech pubs to training to sales and marketing and beyond.

Makes sense, right? Yet attendees at the conference kept coming back to this question:  How do you persuade management to make the investment in DITA tools and methodology in order to reap the downstream benefits across the organization?  How do I as a technical writer or trainer get management to free up dollars now so that we can have better content down the road?

We all know that documentation and training is usually looked at as (yes, I’ll say it) a necessary evil. Corporations provide documentation and training to the user community almost as an obligation, and they aren’t happy about it. That’s because (generalizing here) documentation costs a lot of money, is used infrequently by a small audience, and does not generate revenue or good will. If the discussion centers instead around intelligent content as a corporate asset however, the “necessary evil” aspect is covered. The conversation shifts, and content is no longer an obligatory offering. Instead, it is viewed as part of overall corporate strategy. In addition, corporations begin to view the base material in the repository as an asset capable of generating revenue and indirect income. Anthony Allen, Director of Production for the American Society of Training and Development (ASTD) provided one example of this. During his talk, he described how ASTD’s sales people can now create custom content packages for each buyer by using intelligent content technology to combine a chapter from this book, a chapter from that one, along with a white paper and some blog entries.

Of course, the possibilities extend beyond revenue. Corporations now have the opportunity to create a differentiated brand that will attract users because it’s easier to derive value from your content than from a competitor who does not use intelligent content.

So, again my question is this: Do we need to create, champion,  or develop a new role, something approaching a Chief Content Officer (CCO) or a level or two below in the corporate structure so that documentation is no longer seen as a necessary evil? How would that affect the tech pubs model? Would it evolve in an interesting way? Please comment freely and in any forum you choose. TechProse is active on LinkedIn, Twitter and Facebook.

“Guess what! I’m back to working on a project for HotShotCompany!”

“Oh yea.  What are they up to?” An obligatory response from me, thinking there was nothing particularly special about that.

“Converting from Adobe FrameMaker to DITA,” Linda teased knowing she would pique my interest.

“Hmmm, as I remember you worked with that company quite a while back?”

She paused for an instant to consider the wheels of time and said: “It’s been over eight years, and do you know what I was doing then?”

“Can’t even guess!”

The chuckle in her voice said it all, “Converting from Interleaf to FrameMaker!”

The grey-haired writers out there will be chuckling right along with Linda. For those of you who are lucky enough to have the sparkle of color in your hair, read on and you too will be chuckling.

The point is that the old is becoming new again, and ever-spinning cycles double back on themselves.

A tag by any other name …

Once upon a time, authors tagged content with formatting instructions as they wrote. Applications, such as Interleaf and WordPerfect, used simple tags that looked a lot like HTML to specify content formatting. The tags <b> and </b> would create bold text. Seem familiar?

When HTML first came out, we tagged content for formatting, again by hand, as we wrote. In each of these cases a What You See is What You Get (WYSIWYG) fully formatted view was not initially available. That was the way it was and we all just accepted it without a second thought.

However, the natural evolution of software applications seems to be from painful complexity to ease of use. Eventually, the newest versions of existing applications and brand new applications all promoted WYSIWYG, fully formatted view in favor of hand tagging. We all eagerly jumped on the band wagon and promptly forgot, or tried to forget, all about hand tagging content. We were totally carried away with turning text blue or finding new fonts. It was a fun new world! There was color, shape, graphics, and all this stuff we could not even see before. All we saw was <b>and</b>.

Now, fast forward to today and drop standardized XML markup languages into the single-source well: Standardized Generalized Markup Language (SGML), DocBook, and Darwin Information Typing Architecture (DITA) to name just a few. These are the languages used in the single-source world to tag content.

In the old days, we tagged content to convey formatting instructions. Today, we tag content with XML markup languages to convey information about content, in particular the structural nature of the content. XML tags don’t say, “Make this text blue.” Rather they say, “This content is a task, or a step in the task, or a command in the step.” Tagging in this way is an advanced feature of single sourcing and requires deeper expertise and special tools to support it.

Once we have consistently tagged the content, a publishing system can be configured to do different things with the tagged content. For instance, the same topic with the same XML tagging can be published with fancy formatting to multiple output targets like PDF, online help of many flavors, HTML, and even Microsoft Word, if you want. You can even publish to your iPod, and you don’t have to change a thing in the topic or the tagging. All the formatting magic is done by the publishing system.

Now that is this lazy author’s nirvana! I can write a topic, tag it once, reuse it in bunches of places, and publish it to whatever output is in the fertile imaginations of corporate entities. I focus on the content and let the publishing system consistently handle all the pesky formatting issues.

Go deeper

• Interleaf http://en.wikipedia.org/wiki/Interleaf
• WordPerfect http://en.wikipedia.org/wiki/WordPerfect
• WYSIWYG  http://en.wikipedia.org/wiki/WYSIWYG
• XML Mark Up Languages http://en.wikipedia.org/wiki/Markup_languag
• SGML http://en.wikipedia.org/wiki/Standard_Generalized_Markup_Language
• DocBook http://en.wikipedia.org/wiki/DocBook
• DITA http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

In 1993, I stumbled into my first single-sourcing project. It was a context sensitive online help system. The core features of the product I was documenting were reused in several modules. I quickly realized that meant I could indulge my inherent laziness—write a topic once and use it in many places. The last thing I wanted to do was to copy that topic all over the place, remember where the heck I put it, and then manually update it in all those places. That is my idea of hell! Instead, I authored self-contained and generically written topics, stored them in a simple file system, and updated them there. I wrote batch files that sequenced topics, reusing what I could. Then, I used the batch files to populate and run the help compiler that came with the Microsoft Windows Software Developer Kit. Voilà! I had a single-sourced help file.

To save my reviewers time, I noted where reused topics occurred in the help TOC and asked them to review these topics only once. Reviewers thought that was just peachy! At the end of the project, while my colleagues were sweating bullets trying to update all their copied topics, I just ran my batch files and went home.

In addition to folks like me who were just trying to save themselves a lot of headaches, the people at Information Mapping (IM have been teaching writers topic-based and chunked authoring techniques since the late 60s. Unstructured FrameMaker has had basic single-source features, such as sequencing a series of files by referencing them in a master file, referencing a file in another file, specifying text to display under specific conditions, and using variables to represent text strings since the early 90s. We can also thank the makers of online help tools, such as RoboHelp and Authorit, for promoting single-source features in their software. And even Microsoft Word has features that can be used to support single-sourcing. As a collective whole, the well of our contemporary single-source strategies and tools is quite deep and has evolved under the forge of real-world writing projects. You already use some of these tools and have the expertise needed to use the basic features of single-sourcing.

Catch the wave

Many of us have been working for years in our own little single-source worlds, using whatever tools we could get our hands on, just to do what seemed obvious to us. We went to conventions, shared our tips and tricks, and showed off our results. We got excited when one of us found something that worked and quickly jumped on it. Finally, the tools manufacturers got wise to us and incorporated more robust features into authoring and publishing software to facilitate single sourcing.

Single sourcing is no longer a rare-bird practice of a hardy few. It is an industry best practice that delivers a significant return on investment. Just imagine, you pay to author, review, translate, and publish reusable topics only once. The accuracy and consistency of those topics is maintained automatically. And, your organization can share reusable topics across multiple departments and interest groups, increasing your corporate knowledge transference.

There has never been a better time to be a lazy author and give single-sourcing a try. That’s exactly why we’ve started this blog. Here you can follow us through a single-source implementation in all its glory. We’ll address all the common myths and concerns about single-sourcing, as well as share some of our secrets and, of course, opinions. We encourage you to add in your two cents and share your experiences.

So grab your boogie board and let’s get wet!!

Go deeper

• Single-source defined http://en.wikipedia.org/wiki/Single_source_publishing
• Society for Technical Communications Single-Source SIG home page http://www.stcsig.org/ss/
• Information Mapping (IM) http://www.infomap.com/ and http://en.wikipedia.org/wiki/Information_mapping
• FrameMaker http://www.adobe.com/products/framemaker/?promoid=121DJGSP_P_US_FP2_FM9_MN&tt=P_US_FP2_FM9_MN
• RoboHelp http://tryit.adobe.com/us/robohelp/?sdid=FBLWP
• Authorit http://www.author-it.com/ and http://en.wikipedia.org/wiki/AuthorIT
• Microsoft Word Master Documents http://office.microsoft.com/en-ca/word-help/create-a-master-document-and-subdocuments-HP005187002.aspx