Monthly Archives: November 2007

tools

Q and A about Author-it and DITA – guest post from Mike Stockman

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.

writing

Words are it… from 17 words to topics

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.

writing

Happy turkey day – but let’s talk wiki, not turkey

Anne Gentle and sonHappy thanksgiving everyone! I have much to be grateful for. Here’s me with my son, both of us stuffed full of turkey.

Deadline extended… multiple meaning

I just learned that the Give 1 Get 1 program to purchase two XO laptops has been extended through December 31st. Hurrah!

I’ll admit it – my first thought was, good, I can delay that $400 escaping my bank account until after the holidays. But my second thought was, “Say, we can work more on the simplified user guide to get a nice PDF and even more language translations!”

Wiki writing workflow

I said I’d try to describe the workflow of wiki to Author-it. It’s pretty feeble and I really want better ideas so feel free to offer up your thoughts here.

Some history on the legacy. The file started out as a Google Document, which basically meant it had nice clean HTML code underneath and could be written on collaboratively and shared discerningly. The links to the wiki URLs were actual URLs rather than the wikitext linking code. The text contained a bit of passive voice and was more descriptive than task oriented.

Always start with task analysis

Once I read it, I did some task analysis, which is available in this published Google spreadsheet. I broke down the tasks based on whether the user was a kid, a parent, or a teacher using the XO. Then Emily Kaplan and I started re-writing the sections and adding section (or topics) based on the task analysis. First we tried writing each topic as an unpublished WordPress blog entry, thinking that we could eventually get translations done using the Worldwide Lexicon open source initiative. An interesting concept, perhaps well-matched to the spirit of the OLPC project, but we learned that maintaining a Table of Contents would be difficult, and also found that the Laptop.org folks like SJ Klein really wanted the wiki at wiki.laptop.org to be the source for all content.

Wiki as source

I completely agree with this wiki-centric approach and we have adapted. All the WordPress entries (there were less than eight of them) went into the Google doc, and then Todd Kelsey “wikified” the Google doc by saving it as Word, then using a visual basic script to convert to wikitext. We lost all the graphics placement but were able to get a wiki page going with the Google doc.

Word to Author-it…

During the same week’s time, I had taken the Word document saved from the Google document and imported it into Author-it in the instance donated by Author-it (thanks so much) on a server donated by Hostway (again, thanks) and that import worked really well with graphics and links and pretty much everything intact.

Wiki to Author-it… and back again

But this is where the wiki as source becomes difficult, right? Any changes that are made to the wiki must come over to Author-it, and that’s a manual and “think-tual” process. And I’m behind and should stop writing this blog post and go work on synching and writing more topics based on the task analysis. :)

Localization

As far as translations go, there were several translations done of the document when it was still in Google docs. Interestingly, many of the translators wanted Word documents to work in. Again, though, with wiki as source, I have linked to the translated files in hopes that others will pick up and wiki-fy the translations. One area I’m still learning about is whether the wiki engine has tools for the editors of translated pages to keep up with changes made to the English version and vice versa (if changes were made to the Spanish version of the wiki page, how could we incorporate those into the English version of the wiki page?)

Wikitext, wikitalk

I’m learning so much more about wikis (especially wikimedia) from this hands-on experience – such as “signing” notes with ~~~~ to get your username and a time date stamp automatically, and using “talk” pages to communicate with others on the wiki by posting notes for another user.

XO User Club in Austin

I’m also committed to starting an Austin-based XO User Club, following Robert Nagel’s lead with his excellent blog post and article in OLPC News. Let me know your thoughts here – I would like to see if we could meet at one of the Austin public libraries, probably on one Saturday a month (although we’ll be competing with soccer and other Saturday activities). We might have to play it fast and loose for a while and see what type of core group we gather. There’s a User Groups wiki page at http://wiki.laptop.org/go/XO_Giving/Users and it’s great to see where the groups are cropping up.

How to help

If you’re interested in writing more of the user guide for the laptop, all are welcome to contribute to the wiki page at http://wiki.laptop.org/go/Simplified_user_guide. Use the task analysis as your starting point if you want to start a new topic. I’m also seeking a page layout person with Word expertise to get a nice square manual that Lulu.com could easily print. Graphics to explain procedures, especially using the Activities, are always welcome over text. Join the OLPC Library mailing list where we discuss documentation and e-books for the XO.

Also, consider using the give one get one program to give the “get one” to some deserving kid in Austin, especially now that the GIG1 offer is extended. I’d buy ten of them if I could, to start the XO kids club with no “entry fee.”

Also, join us at the XO club meetings, with or without an XO, if you’d like to bring your Linux or Windows laptop and emulate Sugar, the XO’s operating system. EToys and TamTam experts are welcome.

wiki

Wiki as forum, FAQ, HTML editor, XML editor, or CMS?

Wiki as the new FAQ

I discovered and have been meaning to write about Wiki is the new FAQ, an excellent blog post talking about SAP’s use of a wiki featured in an article in the Wall Street Journal. I especially like the play on words in the title. Reminds me of “brown is the new black” or “pink is the new blog,” hee hee.

A wiki can be a Frequently Asked Questions repository, much like the knowledge bases in their heyday in the late 80s. My favorite line from the blog entry has to be its closer: “It’s about a different way of thinking around how to interact with the community.” And that is what I have explored with my wiki presentation, about how to build community with a wiki and be an active member of that community. But what are other uses of the wiki?

Wiki as the next-generation customer forum

For many information seekers, wikis are better than forums because they are more easily searched and once you get a hit, the articles are meant to be scannable. Compare and contrast this to a long thread on a support forum where the answer to your question might be buried in the middle of a discussion about the mysterious beep in someone’s house. In my beep example, there are literally 78 pages of forum discussion, and if you read through the threads, you discover that a group of people took it upon themselves to go to the person’s house to find the beep. It has probably two years of forum discussion around the possibilities. Quite a fun and entertaining read, though, but not that efficient. Still, consider the community that built up around beep troubleshooting. Great stuff there.

But consider that your software users might not have the time to read through even a few pages of a forum discussion about a solution to their problem. That is where a wiki could be more useful than a forum. While forums are a fun online community for many, wikis might be the new generation of forum and many wiki engines offer comments on each article which are the next evolution of a forum – you can discuss the article itself. Another blogger, Leigh Blackall of Learn Online, discovered “The gold in a wiki is often in the discussion pages.”

Wiki as an easy HTML editor

Wikis originated as the quickest way to create a website without having to know HTML code. Really, wikitext is all about quickly doing headings, paragraphs, and lists.

Unfortunately each wiki has different rules for how to indicate a heading or list item or type of list. For some, it might be easier to just learn HTML code. And in the case of the Drupal CMS, there’s the ability to either use a rich-text editor or hand-code the HTML. It’s easy to troubleshoot when you can just view the HTML code, but what’s odd is that sometimes the resulting <div> tags generated out of your webform entries in Drupal seem to overlap.

But most wiki engines offer the fastest and easiest way to make a web page with a URL that you can consistently refer to.

Wiki as the new book

Some folks are pre-populating their wikis with book content, which is always an interesting test of what parts of a book are considered essential for “bookness” or “wikiness” – do you keep a table of contents? Is there any index? What page metaphors do you subscribe to in the wiki? These questions can be answered by looking for examples and analyzing their success. I especially like using wikis for the wiki aspects that go above and beyond books. For example, I’ve been exploring the Meatball Wiki site (Thanks Janet!) – and they have an excellent page with all sorts of Indexing Schemes categorized, such as Readership and Authorship which are fascinating for use in wikis as opposed to books. The Ontology category seems the most book-like to me, and I really like how that page offers ideas for all the possibilities that wiki offers.

Wiki as the new website

Does any company use only a wiki as its public-facing website?

Wiki as the new Content Management System

Eventually, the wiki can be the source files for important content, and I would guess there are people moving towards this wiki-as-cms system already. With my work with the OLPC project, I am learning more about wikis as source files, and found that the compare is actually quite powerful visually. Take a look at two versions of the demo or release notes from a release done in September. There is color coding and side-by-side comparison of text that is easily scanned for what changed, was added, or deleted. I’m learning so much about wikis for localization and translation efforts as well with the OLPC project. For example, this past week, I added links to translated content, such as the Spanish translation of the Simplified User Guide. The wiki engine itself (in this case, WikiMedia), lets me list the additional language pages in a blue bar on the original page, and then each language page automatically links back to the main language page (in this case, the English page.) Automatic is nearly always useful.

Do you see wikis being the next generation of other documentation outlets? Do tell.

DITA writing

Something old, something new – design patterns

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.)

writing

7 things you must know about ePublisher Platform

  1. Content is king. Your source content can be Word, Frame, or DITA. You can even import convert other formats such as RoboHelp to Word or Frame and go from there.
  2. Formats are separate from content and can be customized.
  3. Combining content is allowed and even encouraged. Mixed content is just fine.
  4. There are great demos (over an hour’s worth) on the Quadralay web site.
  5. ePublisher has an extendable XML adapter. This extensibility means that no matter what XML you’re putting in, ePublisher can be extended to understand it.
  6. You can automate the dickens out of your output build processes and integrate with development’s version control systems and build with the Auto-mapper.
  7. The WebWorks Wiki (uses MoinMoin engine if you’re wondering) has lots of information and they encourage people to contribute to it.
tools wiki writing

Community support – don’t think of yourself as a customer but as a member of a movement

I’ve signed up for the Give 1 Get 1 program for One Laptop Per Child, and just received the email today, November 12, 2007, with the link to the site, www.laptopgiving.org.

group-giving_v2.jpgI read the terms and conditions with interest because I am seriously considering purchasing a laptop either for my son, who is four, or for his classroom of four-year-olds. Plus, I’ve been volunteering to help with their end-user documentation.

I’d love to buy one for every classroom at my son’s preschool but that’ll take some fundraising. I’ll boldly propose here that you can contact me if you’re interested in buying enough for a small preschool in Austin, Texas in addition to kids in least developed countries around the world.

I absolutely LOVE the spirit of the support statement. It reads as follows:

Neither OLPC Foundation nor One Laptop per Child, Inc. has service facilities, a help desk or maintenance personnel in the United States or Canada. Although we believe you will love your XO laptop, you should understand that it is not a commercially available product and, if you want help using it, you will have to seek it from friends, family, and bloggers. One goal of the G1G1 initiative is to create an informal network of XO laptop users in the developed world, who will provide feedback about the utility of the XO laptop as an educational tool for children, participate in the worldwide effort to create open-source educational applications for the XO laptop, and serve as a resource for those in the developing world who seek to optimize the value of the XO laptop as an educational tool. A fee based tech support service will be available to all who desire it. We urge participants in the G1G1 initiative to think of themselves as members of an international educational movement rather than as “customers.”

I’ve been working on documentation for the XO laptop in the wiki at wiki.laptop.org/go/Simplified_user_guide and then taking the wiki content over to an Author-it instance. I’ll write more later about a wiki-based workflow, especially with translation in mind, and we are putting a process in place. Please, feel free to edit that page or contact me if you are interested in contributing.

Personally, the most difficult part so far has been my limited ability with design and layout. I have grand visions but feel my layout skills are inadequate for a kid- and parent-friendly look within Word. Nonetheless, it is an exciting time to be a small part of such an influential project.

I’m one of the friends, family, and bloggers who is willing to help with the XO laptop. So I urge you to go to www.laptopgiving.org and put your U$399 to good use.

Serendipitous trips through the river of information

Anne Zelenka has once again nailed down the idea of how to work in a new world where there are far too many sources of information and no way to use technology to help you sift through that information. So you get on your raft and float along the current, and along the way you find the information you need to get a job done.

In The Future of Ignoring Things on Internet Evolution, Cory Doctorow says “I’ve come to grips with this — with acquiring information on a probabilistic basis, instead of the old, deterministic, cover-to-cover approach I learned in the offline world.”

One of the commenters on Cory’s article talks about navigation, saying “We need a sensible, extraordinary navigational system which helps the things we care about at the moment rise to the surface.” How amazing would your help system be if you could apply this technology to your product’s help?

My own journey – searching information

As for me, I am coming to terms with the idea that I’ll stumble upon useful information. But I tend to think I’m a pretty darn good researcher and that my Google Fu is strong, enabling me to find the best relevancy and authority in my information seeking. The more I travel on the river of information, though, the more I’ve come to appreciate the serendipitous discoveries.

My occupation – supplying information

Since as a technical writer, I write the loads of information that others need to sift through (or travel upon, choose your metaphor), this mind shift seems very important to follow. While Cory and Anne are miles ahead of most of the audience of the product I work on for my day job at ASI, my work on the OLPC project has a very different audience and that audience might be closer to Cory and Anne in their ability and desire to find information probabilistically. So for the OLPC project, documentation in a wiki seems appropriate. For ASI, only subsets of the overall audience might benefit from a wiki, such as the technical implementers using the Software Development Kit.

So, back to the basics it is – consider your audience while creating that flow of information. And keep an eye out for that extraordinary navigational system.

An example of serendipity in information finding

And now for the storytelling portion of this blog post. I often write blog entries and leave them in draft form for a while. This very post happened to be in draft form while I wrote and published my recent Wikislices entry. Sheece Baghdadi, who is a technical writer for Webaroo, saw my link to Webaroo, came to my blog, and posted a comment on my entry. I read Sheece’s comment, and I followed the link to Sheece’s blog, where the current post is about searchradar.webaroo.com, which attempts to address the very problem that “searching is easy but finding is hard.” With the Search Radar FireFox plug-in, additional search queries are suggested to you in a column to the right while using Yahoo or Google. I immediately saw a connection to this post, which was still in draft form. So I added this story to the post. What a journey.

searchradar tag cloudThis type of suggested searches might be helpful to our end-users since the vocabulary varies widely for non-profits, organizations, or churches using our technology. Other searches might suggest a serendipitous path for our users to take to obtain the information they need. Take a look at the tag cloud that offers other search possibilities when you search for “agile” at searchradar.webaroo.com.

Blogs are a great way to find information probabilistically. I think there are other applications of technology that can help our end-users find information probabilistically as well, if they are ready for it.

wiki

Wiki-fy your doc set – slides available

My presentation at the Austin STC community meeting went well last night with nearly 40 attendees and even a pair of writers from San Antonio. I really appreciate the warm welcome everyone gave me.

austin_stc_community.jpg

I used Google Presentations at docs.google.com to create the slides. I’d say it worked really well plus I could print handouts. And, I can offer a link to the presentation after the meeting – slides for A Technical Writer’s Role in Web 2.0 – Wiki-fy your Doc Set.

Lessons learned

  • If your Windows-based laptop doesn’t display on the projector right away when you press Fn + F8, you have to bump the resolution down by right-clicking on your Desktop, choose Properties, then the Settings tab, and then slide the Screen resolution slider over. In my case, I had to go to 800×600. The problem with that resolution was that I had designed my slides for at least 1280×1024. So many times, the content at the bottom of the slide was cut off.
  • Try to remember to hand out the handouts you printed before the talk.

If you couldn’t make it to last night’s meeting but would like to attend the talk, I plan to give it again to the Central Texas DITA User’s Group in 2008 and will likely also give it to the San Antonio STC chapter in either January or February.

Please, feel free to comment if you have any follow up questions from last night’s session. Thanks so much for interacting so well.

techpubs tools

Embedding video in your online help

More note taking at sessions at the Quadralay WebWorks Publisher RoundUp. This session is with Stephanie Cottrell Bryant, author of Videoblogging for Dummies. She’s an ePublisher user who embeds video demonstrations of software within online help.

Customers love video embedded in the online help. Time saving for them, and no need to attend a training class. Her customers love it, love it, love it.

Tool kit she uses – Camtasia studio, Framemaker, and WebWorks ePublisher.

Need a script – but you might already have it, like a list of steps in a task.

Annoyance – don’t take your whole desktop while capturing screencasts. “Your desktop icons are like seeing your underwear on a clothesline.” :)

Also, don’t show the time of the day (like 4:00 AM) that you captured the screens, it’s sort of too much information.

Sizing of about 320 by 240 is about the right size for YouTube. Or 480×360 if you need something slight larger. If you’re delivering the video on a hard drive (installed as part of your product), you can make it even bigger. But for Internet or CHM deployment, keep it small.

Record audio first, then replay the audio while you record the video – the timing will be easier to get synched up.

She likes to use a “highlight click” feature that shows a subtle red circle showing where you click on the screen. She also modifies the cursor so that it’s larger and a yellow color while capturing the screencast.

She “cropped” out the first part of the video where she moved the screen around to the optimal location.

She recommends Flash for video output (.swf file). But if you know people are using Windows, you can make Windows Media files. If you know they’ll only be played back on an iPod, make a QuickTime file. If you want to send these video files to someone else and they don’t have Camtasia, save them as AVI – they’ll be larger files but the recipient will be able to compress them as needed and make another format. Also, any video editing software can edit AVI files.

If you want to use embedded video within an HTML file, don’t use Flash, however.

Goes into Frame, creates relative path to the movies (which is in Files folder within the ePublisher directory system), then generates the HTML using ePublisher.
She uploaded javascript to the WebWorks wiki that writes the embedded video code in on the fly, so that Internet Explorer doesn’t put a popup in front of the user, complaining about the embedded object.

In the javascript call to the video file, she’s adding an extra 10-20 pixels to the height dimension so that the player bar shows up at the bottom.

She uses conditional text in FrameMaker called “Passthrough” for all her javascript code so she can put it right into her FrameMaker file.