just write click

The April 2008 issue of the STC Intercom magazine is dedicated to DITA (Darwin Information Typing Architecture).

I’m pleased that the Building a DITA-Wiki Hybrid article that I co-authored with Lisa Dyer and Michael Priestly is available online for free to anyone, STC member or non-member. The article discusses these three ideas for merging DITA and wiki technologies:

• DITA Storm, an online DITA editor with an edit button on each page. While it’s not quite a DITA wiki, it seems like it could become one with some RSS notification and comment or discussion ability on each page.
• Wikislices are a cross-section of a wiki such as Wikipedia, currently created with school curriculum in mind. Michael Priestly and I are working on a team to find ways to use DITA maps to manage and build wikislices.
• Lisa Dyer has implemented DITA as a single-source with wiki as output for a documentation site housed behind a Lombardi customer support login.

I’d love to hear your comments on the article here and any other ideas you have seen for a DITA-wiki hybrid.

From http://dita.xml.org/book/central-texas-dita-user-group

Using DITA Content for Learning Content Development

John Hunt, of IBM, will give a presentation regarding the use of DITA for learning content. He’s been working on a new Learning and Training Content specialization that will be part of OASIS DITA 1.2 release. If you’d like to do a little pre-work, check out this article about using XML (such as DITA) for learning content: http://www.ibm.com/developerworks/xml/library/x-dita9a/

Presenter

John Hunt, DITA Learning and Training Content Specialization SC chair. John is also DITA Architect and Learning Design Strategist in the Lotus Information Development Center at IBM.

I’m also looking forward to Mike Wethington’s presentation to the DITA user group for the May 21 meeting, where he will talk about Agile development and its affect on technical communications. Mike’s the manager of technical communications at Troux Technologies here in Austin.

I’m continuing my musings on connected conversations and tech pubs since there were such great comments and conversations going on with it.

I had an “ah ha” moment at SXSW Interactive, when one of the social media metrics panelists Rohit Bhargava said he sees three areas or channels for measurable conversations - Public Relations, Marketing (Sales), and Customer Support.

For me, those three categories crystallized this connection: where our role as tech pubs is strongest in an organization, that’s where we might start successful conversations.

Gordon McLean’s post cites Marketing and Sales as a strong tie-in, and sure, I’ve seen that and worked in that type of environment. Marketing concepts such as Business Service Management and white papers about ITIL were the primary reason and communication idea I used when I started my blog at talk.bmc in 2005. Product documentation that helps drive sales or close deals is a great method for proving our value.

Tech support seems the best alignment for many companies, as Charles Jeter’s follow-up points out. Tech publications that drive down support costs are another area where value proof lies.

Where tech writers don’t stand much of a chance, based on my limited experience, is public relations. We tend to be a fact-finding lot, not the “spin doctor” type, nor are we necessarily prepared or educated in the ways of crisis communication. I myself cringe to think of having to write blog entries for Southwest Airlines after the recent safety fine. There’s a great case study on crisis communications at BlogWrite for CEOs - Case Study: Southwest Airlines’ Corporate Blog and Crisis Communications and reading it makes me realize how difficult it can be to blog for a company as a representative of a company.

Now, my question is, will companies pay technical writers for a conversation rather than a deliverable? Perhaps only if there are some metrics to prove worth and value.

Sarah O’Keefe wrote up a nice summary of the WritersUA Pundits Panel, and Bogo Vatovec (of Bovacon)  made a statement something like this:

Introverted technical writers will not be writing help any more and will be replaced with experts moderating support forums. … Technical writers can no longer afford to hide in their cubes, they must go out and become experts and talk to the users.

I left a comment on her post that I see a similar future for our profession, although I do not have a value placed on introversion versus extroversion - likely introverts make perfectly good community managers and forum moderators since they can do that from their desks for the most part.

But, it does take some bravery to put your real personality online. I’ve found that a few of us are doing that - going from technical writer to blogger writing directly to customers.

While many of us blog to an audience of other professional writers, there are technical writers out there who are blogging to their end-user audience. Here are two examples:

• National Instruments here in Austin has a blog called “technically speaking” that they use not only to talk about their daily work but also to keep their end-users informed about documentation. For example, here’s a post about a wiki that LabVIEW users will find helpful.

• Another example is Dee Elling’s blog for CodeGear users. This entry offers a great example of a real conversation with customers. I applaud her bravery (and emailed her to tell her) in facing these sometimes abrasive responses with a sense of customer service and helpful attitude. She doesn’t always have a good message to bring (they are working furiously to give their customers more code examples which we all know is time-consuming and difficult). But she brings a message directly to customers anyway.

Is anyone else talking directly to their customer base with their blog? Consultants in technical writing and content management are definitely talking to current and potential clients - Palimpsest is Scriptorium’s blog, The Rockley Blog, The Content Wrangler, and DMN Communications to name a few. But what about conversations with end users? I’d love to see more examples.

Steve Carl already wrote up his notes from BarCamp Austin and I enjoyed his viewpoint very much. This was only my second BarCamp experience, and this year, I decided to take the plunge and actually volunteer to present. Whurley was very encouraging despite my inexperienced questions. “What’s a badge that you wear vs. a badge for your blog?” for example. There are graphics for each, as it turns out. The graphics are completely awesome, and the t-shirts were great, arriving despite an actual train derailment preventing the first shipment from arriving on time.

For those not familiar with the BarCamp format, it’s an unconference where you show up in the morning and put your session into one of the time slots on a white board or on a post-it note. The wiki also had sign-up schedules but the hand-written timeslots at the event win over the wiki page.

The week before BarCamp, I went to the wiki’s Sessions page, clicked the Edit button, and wrote up a short description of a session called Hug the XO. I basically wanted to see if others could bring their XO laptops and I could show them the tricks I’ve learned recently, plus run the Sugar emulation on my Dell laptop.

Getting to Idea City

(photo by Chad Hanna from theotherpaper on flickr)

The morning of BarCamp, getting to BarCamp turned out to be more difficult than I had planned. I got downtown by 9:00, but couldn’t find the Silver Dillo to ride over to 6th and Lamar to GSD&M’s Idea City. So, I took a few touristy photos of Ester’s Follies and the row of SegCity’s Segways, turned around and went back to the Austin Convention Center. I attended a 10:00 SXSW Interactive session, Creating Findable Rich Media Content, and then went back to Sixth street seeking the ‘Dillo. I walked about five blocks until I was past Congress Avenue when I saw a Silver Dillo sign and a person waiting at the sign, then turned and looked up the street to see the trolley coming our way. I double-checked with the woman waiting to make sure there wasn’t a charge since I was silly enough to have not gotten cash out, and sure enough, it’s a free ride. I boarded the Dillo and was on my way.

Getting into BarCamp

Idea City itself is an incredible workplace, full of creative vibes and a wonderful open design with full windows in front. Steve Carl greeted me, I registered with a cool registration application that Twittered my arrival to @barcampaustin (very cool), I had my picture taken for the flickr photo stream, and Steve and I proceeded to the schedule board to see where I could fit in my pres. I really felt more like doing a demo than a full-fledged presentation, so I was happy to see that the demo room had a free half-hour slot at noon. I drew little XO icons on a post-it, titled it “Hug the XO” and headed upstairs to figure out the room layout. On the way up, I saw my old BMC buddy Cote, and ran into Decibel, a good friend of my husband’s, and also met Snax finally, having friends of friends of hers.

Hugging the XO

In the demo room, I hooked up my laptop and ran the Sugar emulation image downloaded from the RedHat Site by using QEMU. In emulation the Activities run pretty quickly, and it’s very easy to display on a large screen. There’s discussions surrounding a projection display for the XO itself, but it’s easiest to emulate for me.

I showed Turtle Art which is really exciting to programmers. People expressed an interest in showing the XOs at Codemash because there’s a grassroots Kidsmash that happens in parallel, so I’ll definitely be following up with Josh on that idea.

I also learned some neat tricks to get deeper into the XO. One way to view the files on the flash memory without using a command line is to launch the Browse Activity and type file:///home/olpc/ as the URL. Now that is a handy shortcut.

I also learned that you can transfer files to and from the XO by using scp from the Terminal Activity by reading the XO setup user guide at OLPC Austria. First, get the IP address by typing iwconfig at the prompt. Then, you can use these instructions:

To upload the file test.py from a pc to the xo (into /home/olpc), use: scp FILE_NAME USER@IP:TO_DIRECTORY

scp test.py olpc@192.168.0.2:/home/olpc

To download the file /home/olpc/xo_test.py from the xo to a local pc, simply reverse the arguments:

scp olpc@192.168.0.2:/home/olpc/xo_test.py ./

We finally got the Acoustic Tape Measure Activity working correctly, and I’ve updated the instructions on Floss Manuals appropriately. Test your task instructions, I always say! Fortunately, this was a fun one to test. We had to have the laptops beep at each other at least 4-5 times before the measurements came into a reasonable range, starting out at nearly 200 meters, and eventually settling on just over 3 meters. Success! The noise they make to each other almost sounds like they’re spitting at each other. Kids will love this activity with a pair of laptops.

People really enjoyed the Speak Activity and we laughed to discover you could give it multiple eyes.

I think we had at least a dozen people stop by the demo room, and after the demo session was over, we set up two of them near the lunch pickup line. Steve was nice enough to “babysit” the XOs while I went back to some afternoon SXSWi sessions, and he said he thinks at least 100 people got to see and try out the XOs for themselves. We downloaded Flipsticks, played some Tam Tam Jam, showed off the Browse Activity, surfing to any URL we needed to, and generally had a great time. We met other XO owners and I told them about the XO-Austin users group, and told everyone they could meet us at Las Manitas on Sunday for an XO meetup. I’ll write another story about my lunch meeting with SJ Klein from OLPC, Robert Nagle, the XO-Houston user’s group organizer, and Melissa Hagemann from the Open Society Institute (OSI). We had a great time together.

Summing it up

This experience was such a great opportunity for me to talk to people about things I believe in (kids, technology, and education) while having fun being a technical writer. I was intimidated initially because I’m not a programmer, and so I wondered if I’d be questioned for even volunteering to present, but I realized that no matter how technical I was, I would be less technical than someone in the room and more technical than someone else in the room. So, the correct action to take is to share the knowledge you have and listen to others to learn more about the topics that interest you.

My only regret from BarCamp is not staying longer for Dawn Foster’s talk about Community Management. I had asked my husband to meet me at the Convention Center with my two sons so we could go to Screenburn together, but after seeing how intimidated my four-year-old would have been by the shoot-em-up video games there, I cancelled on them and wished I had stayed at BarCamp longer. I’ll just have to settle for reading Dawn’s notes about her BarCamp experience instead.

One reason why I like the show Dirty Jobs so much is because Mike Rowe, the host, is so respectful and honest about the work that people do each day. Dirty Jobs offers such a great viewpoint on work that is done each and every day. I recently discovered that Sarah Maddox, a technical writer at Atlassian (makers of the Confluence wiki engine), has written two great posts about being an Agile technical writer, or an eXtreme Technical Writer (XTW). These posts on Agile Technical Writing offer wonderful windows into the work that technical writers are doing around the world. Plus, they offer some down-to-earth how-tos that make sense to apply in a modern technical writing career. If you’re thinking about technical writing as a career, check out these two posts for your research, because I believe that agility is one of the best skills you can bring to this career path when I consider the direction it is heading.

• The agile technical writer is the first post, and it has a great description of daily life as a technical writer.

• Plus don’t miss the great photo art mashup in the agile technical writer part II, another excellent post that really describes what it’s like to write in the Agile development environment.

Here are some highlights from each that I could identify with:

• Responding to IMs from all over. Carrying on multiple conversations intelligently is a gift.
• Concerns about information overload - it’s daunting, but do-able. (Okay, funny side note - My typo for overload was “overlord.” Yipes. That can happen too.) My advice is to ride the serendipitous river of information. Sounds like hippy advice but somehow it works.
• What a wonderful viewpoint of how the daily life of a technical writer has changed so greatly over the years. I listened to Linda Oestriech’s podcast about the Direction the STC is Heading at Tech Writer Voices and one great quote from her was, “We’re not the technical writer from the 70s.” I’d say we’re not even the technical writer from the 90s.
• Love the Swaparoo idea - similar to pair programming, but call it a swaparoo when you want to trade tasks with another writer to get cross-product knowledge.
• Respond to customers from the varied means of communication that is offered to you in this awesome world of documentation. And if it doesn’t have to do with the doc, don’t meddle, pass it along to the support team.

Thanks Sarah, for sharing such a great “day in the life” slice for technical writers.

Authoring and delivery tools for the Agile Technical Writer?

I’ve had a question via email recently, asking something like, “What is the ideal toolkit for writing in an Agile environment?” Or, “What would you choose if you had to write in an Agile environment in order to be most effective as a technical writer?”

It’s tempting to actually try to answer that question with a straightforward response of one tool - but of course the answer is not that easy. The product and audience and company that you’re writing for all dictate the documentation deliverable with far more weight than the “manufacturing” process that is used to build the product. Sarah’s posts don’t directly mention their toolkit, but her “eat your own dog food” bullet point hints that the doc is delivered via their wiki engine. (Sarah, do correct me if that’s an inaccurate leap in logic.)

But, if the product you’re documenting isn’t itself a wiki, you’re going to need to evaluate tools. I borrow directly from Don Day’s editor evaluation heuristic for a methodology for evaluating a writing and publishing toolkit to fit in an Agile environment. Evaluate a tool (no matter what you’re trying to deliver or how you’re authoring it) using “cost/benefit judgments on the features that mean most to your intended scenarios, business rules that need to be supported, and the willingness of your team to learn some new ways of doing things.” Well stated, Don, and whether you’re trying to find the right DITA toolkit or the right Agile toolkit, scenarios and business processes are quite useful. Anyone have great authoring or publishing scenario or business process suggestions for the XTW?

DITA for writers (content creators)

I just did a search on amazon.com for books for beginning technical writers and also to investigate what books are being written for our profession and for others wanting to start in our profession. I came across a book called Writing Software Documentation: A Task-Oriented Approach that suggests three categories for writing:

• writing to teach (for eager learners)
• writing to guide (for reluctant users of the product)
• writing to provide a reference (for experts who need only occasional support)

I immediately saw a connection to the three content types that DITA prescribes:

• concepts to teach understanding
• tasks to guide performance
• reference to offer facts or lists of information

Because writers have to immediately place the information they want to record into one of these three types of information, they are being trained on how to write in a task-oriented, performance-based manner, via DITA. I am especially interested in this “training” for wiki authors and talked about the idea at our recent presentation at the Central Texas DITA User Group meeting.

DITA for publishers (formatters)

Recently a few techpubs bloggers have been talking about DITA and its weaknesses, such as a lack of online help outputs, and how difficult it can be technically if you don’t already have a staff with pseudo-programming skills. Gordon Mclean writes “DITA is not the answer” and I think the question he is trying to answer is, “what is a single-sourcing tool we can use in our environment (which includes Technical Communications, Training, Pre-Sales and Marketing) with our current resources?” Instead of DITA, it looks like he’ll go with Author-it.

Since I just this past year moved from BMC, which is still moving to DITA, to a small techpubs group that uses Author-it, I can understand his reasoning and agree with his business case assessment. The toolchain for DITA is very nearly there, but often a CMS-based approach has too much overhead for small companies. It can be cost overkill when you have few topics to contain.

Scott Nesbitt followed up with his post, “DITA’s not THE answer for single sourcing.” I think he’s spot on with the analysis “it’s difficult to get good PDF or online help from DITA without extensively customizing XSL stylesheets or passing DITA source files through tools like FrameMaker, Flare, or WebWorks.” One of his commenters said something about consultants smelling blood in the water, yikes. In other words, I think he meant that XML consultants knew how much customization would be desired and can have a feeding frenzy on the potential work possibilities. My guess is that the people who have been around XML for years know that there are still basic needs for output, and their experiences have shown them that nothing that is structured is an “out of the box” experience. So much of the success depends on your content to begin with.

I’ve found the same conclusions about the output in my experience. When you dig into single sourcing, be it with DITA or another tool (Madcap Flare, Author-it, FrameMaker, RoboHelp, and the Adobe Technical Communication Suite) the real business-case killer seems to still be, where can I get pretty PDFs that are formatted just as I like them? With DITA, one answer is to go get the Mekon FrameMaker plug-in for the DITA Open Toolkit. No XSLT-FO knowledge required.

People love their tools to get their pretty PDFs or sleek online help systems. Plus, so many of the employers out there have a lot of content that looks pretty nice already in a specific tool. The legacy documentation may be one reason why hasn’t DITA helped our industry get away from tool love. Tech writers and their employers fall in love with tools. I’m not saying Gordon or Scott are tool lovers, but certainly some people they’re hiring will be. There is probably also an element of “if it ain’t broke, don’t fix it.”

DITA for all?

Sarah O’Keefe has a thought-provoking analogy in her comments on her post signed “DITA Dissident.” The analogy is that creating desserts using a frozen pie crust is one method of getting results. If a pretty PDF is your ultimate dessert, then for some, DITA is a bag of flour, meaning you’d better be a skilled baker if you’re going to use it for the best pie (PDF) ever. For others, DITA is a frozen pie crust that makes a perfectly good cherry pie (PDF) or apple pie (plain HTML) or chocolate creme pie (Eclipse help). Although isn’t the filling the content and the pie crust the DITA map?

Their conversation first started with Eliot Kimber discussing DITA’s use for narrative documents. Alan Porter talks about DITA use for narrative writing as well, but in a different line of thought in his post, Is DITA Just a Story?

All the posts I’ve linked to are enjoyable for me to read and to point to and to think about. I’ve read it before, and I’ll say it again, I believe along with others that DITA has the potential to transform our industry. Just last night I said to the San Antonio STC group, today we all speak HTML tags pretty fluently. In ten years, will we all speak DITA tags just as fluently? “I wrote the shortdesc according to the guidelines and it works for the topic, but I am not sure if my conref target is going to be there every time. I guess I should rewrite the concept topic.” Heed the warnings and experiences of others before making the leap to topic-oriented single-sourcing or your expectations and those of your customers may not be met.

I read this recent conversation on the author-it-users Yahoo Group with interest. I haven’t had a need to author DITA topics with Author-it, so I have to rely on others for information on how it works. With Mike Stockman’s and Tony Watkin’s permission, I’ve written their Q&A as a blog entry.

Tony: What are your experiences with using Author-it for DITA output?

Mike: The DITA output is partial. That is, they don’t support a lot of DITA features, so that most table definitions are not passed through, bookmaps aren’t supported (although ditamaps are), reflinks aren’t supported, syntax diagrams aren’t supported, and so on. However, it’s definitely usable, so that AIT puts out the four DITA topic types (task, reference, concept, and base) properly structured, index entries are supported, tables and images are handles correctly, and so on. The best test would be to publish to DITA and see whether the results are what you’re expecting.

Tony: Is there a mechanism provided by AuthorIT for being able to search within the DITA XML generated output afterwards from within the browser when accessing the DITA output directly from the browser (i.e. not via AuthorIT)?

Mike: There is no mechanism provided by AIT for viewing DITA output. Once you have the DITA output, you can either view the XML code, or transform it into something more viewable, such as XHTML or PDF. Grab the DITA Open Toolkit, available at <http://dita-ot.sourceforge.net> for all of the tools you’ll need to transform the DITA into something else.

Tony: Also, does AuthorIT just output XML when publishing DITA or does it also produce corresponding XHTML?

Mike: AuthorIT publishes DITA by first publishing to XHTML, and then transforming that to DITA. It does not, however, leave the corresponding XHTML behind, so you can’t view it. Your choices for viewing XHTML would be to either publish from AuthorIT to XHTML directly, or transform the DITA to XHTML.

Mike’s final comments

AuthorIT’s DITA is not a fully-developed DITA solution, so don’t expect it to be. Instead, AuthorIT’s DITA output is great when you have a need for single-sourced output to multiple formats, such as if you needed Word, XHTML, *and* DITA. Where I work, for example, we use AuthorIT’s Word output for our printed docs and PDF, and use the DITA output to create our online help. If you need the advanced features of DITA that AuthorIT doesn’t support, I’d suggest going to an all-DITA authoring environment and avoid AuthorIT altogether.

I say I don’t listen to many podcasts, but I’m currently listening to Design Critique’s podcast with Gerry McGovern at the User Interface 12 conference. Timothy Keirnan was a MTSC classmate of mine and does an excellent job interviewing usability professionals for us all to learn from.

One of Gerry’s comments that really hit home to me is that Google’s entire ad revenue generation is based on 17-word ads. Seventeen words! I complain about the 140-character limit in Twitter, yet, lots of money is being made on seventeen words.

Also, they both noted that generally, web site design is so flat - rectangles and boxes are pretty much all you get. So websites should be useful and functional. And words matter. For example, if you are a non-native English speaker approaching a website for information, you’ll be more successful by recognizing the word “search” quite quickly.

I was also reminded of Harry Miller’s podcast, The IM Model of Technical Writing, about writing end-user documentation as if you were responding to a friend’s Instant Message (IM). Topic-oriented writing such as DITA encourages you to encompass ideas in discrete bundles - topics contain only as much information as is needed. From the specification: “A topic is a unit of information with a title and content, short enough to be specific to a single subject or answer a single question, but long enough to make sense on its own and be authored as a unit.” Very IM-like, I’d say.

An enjoyable couple of podcasts, and quite appropriate for my current thoughts about the value of good writing along with good design.

I’m feeling a little late to the party of patterns that I’ve been reading about lately, but after attending Michael Hughes’ STC webinar presentation “Pattern Language as a Workshop Management Tool” where we saw patterns for user assistance, and we were really intrigued by an internal wiki page he pulled up giving DITA patterns to IBM info developers. Turns out, he had read my wiki article from STC Intercom and has been working on that internal wiki for a while.

His article, “A Pattern Language for User Assistance” is an excellent read. He introduces the idea that you can use a template to describe where a user might be triggered to seek assistance and then describe how to contextually place assistance and offer wireframe models for others to follow when implementing user assistance. A pattern template can be as simple as “here’s the context, here’s the solution, let’s name it as the How-to pattern.” Michael Hughes’ pattern template is slightly more complex but context and solution are the basic elements.

I went on the hunt for more examples of User Assistance Patterns. I found both JoAnn Hackos’ article “Design Patterns: Creating Consistent Information Designs for Print and Web and the DITA design patterns article on DeveloperWorks. Both are great article, and as a co-worker said, the guys at IBM are doing some of the most advanced information architecture and design available today. And even two and three years ago I might add.

Our group discussed how we’d really like to ensure that our user assistance (UA) patterns follow DITA’s patterns – because in Austin, more and more writers that we would potentially hire will be familiar with DITA. So if our UA patterns already match DITA’s patterns, it’s that much easier to get a new writer up and running.

Don Day said that there is a new Help workgroup with the OASIS DITA Technical Committee that will specify patterns for organizing UA sets. This type of work would help immensely with merged help sets even within one company, not to mention plug-ins for open source software projects and the like.

Don also alerted me to the DITA Troubleshooting plugin contributed by an info dev team at IBM. I plan to investigate further because that work would give any information architect a huge head start on designing topics for troubleshooting. An excellent reusable pattern indeed. They even have 12 role-based elements for use in responses when there is a problem - I imagine the use is for writing different instructions for sysadmins who might respond differently than end-users - but I’d need to really study the implementation.

Bob Doyle has mentioned patterns as well, in this Best Practices Reporting with DITA post. He sees the helpfulness of Object Oriented Design Patterns - which are the famous example among programmers - and he proposes a design patterns domain. Very interesting idea.

So while in some ways I’m late to the pattern party, in other ways, many opportunities still abound for reusable patterns in user assistance and other design patterns for technical communication that can be DITA-based. The ultimate vision - one set of patterns that all technical communicators can use and that these patterns plug in with each other with few seams. (Sewing metaphors should be allowed. This is about patterns, after all.)