Monthly Archives: July 2007

wiki

Interview about wikis for tech doc with Dee Elling of CodeGear

While researching my STC Intercom article about wikis and technical documentation to be published in a few months, I interviewed Dee Elling via phone and email because she left a helpful comment on my talk.bmc.com blog entry about a DITA and wiki combo. Dee’s the manager of the documentation group at CodeGear and she blogs at http://blogs.codegear.com/deeelling/.

Anne -What are some of the factors for selecting a wiki software package?
Dee -I’ve encountered hesitation from some writers about using a markup interface. Many writers preferred a Word-like GUI interface, such as Confluence provides. Another consideration is cost, since there is not always a budget for new systems; at CodeGear we use MediaWiki. Primarily we manage internal information such as schedules and doc plans; lately we are collaborating with engineers to write FAQs and release notes.

At my previous employer, one engineering team was writing the documentation themselves on the wiki (using outlines provided by the writer), and the writer cleaned it up and converted it to PDF for distribution with the product. That is a great use case which I believe could seed the adoption of wikis into the documentation process, especially in companies where there are limited doc resources.

At CodeGear I can post copyrighted material to our Developer Network. The Developer Network technology allows comments on postings, which is not the same as wiki but a good start. Since joining, I have started to post traditional doc content as “articles” there. I’ve already fixed a few doc issues due to rapid customer feedback! We are also working on a design to make the website interface more wiki-like.

Anne -How do you get legal approval for such an open-edit site?
Dee -At my previous company I never got to the stage of implementing a public wiki. However I had many discussions about the legal aspects elated to the product documentation. The legal aspects seem complex, but lawyers can write new terms for new situations.

At CodeGear the issue will involve intellectual property, but the user base is so active on the internet that there are few “secrets”. More important will be the issue of releasing information too soon or otherwise getting in trouble with SOX compliance. (That makes my head spin!)

Anne -What are the considerations when choosing where the wiki is hosted?
Dee -Cost and reliability are factors, but most important is buy-in from the IT department, who would likely manage the hosting.

Anne -Which types of products are best targeted for a wiki?
Dee -Complex software products are a good example. There is so much flexibility in software and product documentation cannot cover every use case. The wiki lets customers add content that is relevant to their own use cases, and that will benefit others.

Anne -How can you encourage your users to contribute?
Dee -Keeping up a dialog with the customers is helpful. If you respond to them, a dialog develops, and they are more likely to contribute again.

Anne -What are some of the success factors for the wikis that contain
technical documentation?
Dee -Does it result in more positive feedback from customers? Do customers help each other and contribute to strengthening the installed base? Does it increase product visibility and mindshare in the market? Is it perceived as a strategic advantage over competitors? Does it cut down on tech support phone calls?

Anne -What traps should be avoided?
Dee -The trap of not responding or not paying attention. Writers must diligently track the “living documents” they have created, and they must truly collaborate. If customers contribute and their contributions go unrecognized, they may think that the company is not fully supporting them.

Public wiki documentation must be actively managed and that takes more writer effort than in the past, when documents were forgotten as soon as they went to manufacturing. Contrary to the fear that with wikis you don’t need writers anymore, I believe that with wikis the role of the writer will grow.

Thanks so much for your help, Dee, and for sharing your experience with all of us who are interested in the best ways to harness the power of wikis for end-user doc.

DITA

Frame 8 is here: conversion or migration from unstructured FrameMaker to DITA

FrameMaker 8 was released yesterday, with DITA possibility built in, but you will need to do your homework to determine the best path to migrate legacy content from unstructured Frame to DITA. Questions such as Unstructured to DITA – Concise Conversion Information Needed and What are the steps to convert an FM book to DITA To CHM? are consistently appearing on the Adobe Framemaker 7.2 application pack forum. While conversion is part of the migration process, you have to examine your content and get it to a point where it could be converted, so I prefer the term migration to conversion.

I did some research on this topic, attempting a conversion of legacy unstructured Framemaker content to DITA, and wanted to write it up here in case it helps others.

In my experience with Frame 7.2, I wasn’t able to complete the entire complex process, partially due to the unstructured Frame files, partially due to my limitations in getting XSL to work through Framemaker and writing a Framemaker structured application. Feel free to comment on these instructions if you have questions or ideas for where this process may not work well. Note that I haven’t fully studied how this process might change with the introduction of Frame 8, although many of these tips and tricks will still be useful for preparing your content.

Content preparation tips and tricks

If your Frame content is not already written in topics and pretty well structured, work really hard on getting the legacy content into some sort of order that will help in conversion. For example, make each Heading a topic starting point. Next, you may want to type the content into task, concept, reference beforehand using style tags to indicate what type of topic the content is, such as heading1task, heading1concept.

Indicate your task step numbered lists with a different style name from “plain” numbered lists.

Write your abstract and shortdesc (short descriptions) as initial paragraphs of each topic.

Use test Frame files that have few paragraph tags used. Add in paragraph styles one at a time and test the step-by-step process to make debugging easier.

Use a subset of DITA tags for your conversion, meaning you will be converting content to topics with fewer tags than the full DITA tag set. After conversion you can re-tag the content more specifically but having fewer tags to go to means less troubleshooting for the conversion itself.

Performing the conversion

The overall steps for the conversion involve the following tasks:
1. Structure the current unstructured FrameMaker document with the conversion table and rules text file as mapping helpers.
2. Open Frame book file and import the EDD or Element Definition Document, a proprietary FrameMaker file that correlates to a DTD (Document Type Definition).
3. Save the new resulting file as XML, either using a customized migration structured application that applies custom XSLT, or using the DITA Application Plug-In (which is a structured application also).

Each overall step is described in the tasks below.

I’ll also describe the files you’d create to start such a conversion. To create a structured application, you create a new folder in a C:\Program Files\Adobe\FrameMaker7.2\Structure\xml\ directory. This folder contains:

  • A text file that tells FrameMaker what XML means in its own formatting conventions. For example, it tells Frame that the “xref” element is a cross-reference in FrameMaker.
  • A Document Type Definition file that works in concert with the EDD file that FrameMaker needs to interpret the DTD.
  • An Element Definition Document required by FrameMaker. This file is what you import into a FrameMaker chapter file.
  • An XSL file that could transform FrameMaker XML into separate DITA topics rather than maintaining many topics in each chapter file, instead each topic would be in its own file.
  • A structured FrameMaker file containing the configuration information for both the DITA plug-in and the new structured application that could use the XSL file for transformations.

To apply the conversion table

1. Open the Frame book file that has had the EDD imported into each chapter file.
2. Open the conversion table file.
3. Click File->Utilities->Structure Current Document.
4. Select the conversion table file name from the drop-down list, and then click Add Structure.

To apply the EDD

1. Open the Frame book file and select all chapter files using Shift+click.
2. Click File->Import->Element Definitions.
3. Select the EDD file name and click Import.

To save as XML

1. Click File->Choose Structured Application. Select either the trx-migrate structured application or the DITA-Topic-FM structured application.
2. Open the Frame book file and select all chapter files.
3. Click File->Save As and choose XML.
4. If you are using the trx-migrate application, the XSLT would be run on this step. If you are simply saving as DITA XML, then you would choose DITA as the Structured Application from the File menu.

Comments on the conversion table

The conversion table takes existing content and maps each paragraph and character style to an XML element, then wraps the elements in outer elements as needed. To accurately portray the information and ensure that one change doesn’t affect other areas of content, you must modify this table one element at a time and then check for accuracy. The conversion table is a painstaking and time consuming project in itself, depending on the complexity of the content you have to start.

Manual cleanup and DITA map creation

According to this article, you would have additional manual cleanup of graphic importing, copy and paste for all table cell text, creation of cross reference links, and creating the hierarchy for your DITA maps because of the flattened nature of the saving topics at the heading level.

Reading list and references for conversion

Retro feeds, or time warping your RSS reading, a mash-up proposal

Is the world ready for time-warped RSS feeds?

Electronics technicianElectronics technicianElectronics technicianElectronics technician

As feed and subscription technology ages ever so slightly, I thought there might be a need for the ability to read RSS feeds only from a certain window of time. Plus I had just finished the book “The Time Traveler’s Wife” which seems like chick lit until you realize it’s practically science fiction, or speculative fiction, an amazing love story entwined in the leap of faith the reader takes, accepting that the husband can time travel. That powerful book left me wondering about the passage of time and how to immerse yourself in another time.

So, about two years ago I wrote up the idea, and what-do-you-know, Bloglines has added a longer time span to their return content feature, allowing you to read from feeds from 2001. When you’re logged in and on the Feeds tab, click the Search tab in the right-hand pane and then click More to get the advanced search.

One usability note in case anyone at Bloglines reads this: it might make sense to have the second set of date selectors automatically be set to December 31, 2001. 

This post outlines some use cases for this RSS search specialty.

Overall description of retro feeds, or time-warped feed reading

The general concept is a mash-up of archive.org and an RSS aggregator like Bloglines. One approach would be to design and create a plug-in that would work with many of the popular RSS aggregators, or, another approach is to write a web form where users just enter the feed URL and the date window.

Use cases for retro feeds

Many thanks to Charlie Wood at Moonwatcher for his use cases so I could expand on those excellent RSS use cases for time-warped RSS use cases.

Please, let me know your feedback on these use cases. Are there other uses for retro feeds that I haven’t covered? Have you ever needed to limit your blog searching with date boundaries?

tools

Initial review of AuthorIT

I’m now writing in an AuthorIT environment. My first learning task is to find out the proper pronunciation, is it Author Eye Tee? Or Author It? Let’s see what wikipedia has to say about AuthorIT. In their article, they consistently refer to the product as Author-it, so I would suppose the second pronunciation I proposed is the correct one. Plus, the AuthorIT website has Authorit throughout. Internally we call it AIT for short.

At first glance, the product looks and feels like a database-centric content management system because of the initial connect you make is to a SQL Server database. But in fact the way you browse the system is folder-based, as if I were using Windows Explorer. So far, so good, except that I’m not yet completely familiar with the way that the CMS folder structure is set up based on our Function-based teams. However, we have a Helpsite that lets me browse the current content in another way and has a decent search mechanism and index to allow me to look for the topics I’d need to update.

What I’m doing now to get started as a greenhorn with both the toolset and the product I’m documenting is to peruse the Helpsite which is organized by tasks and features of the product, and then determining what topics need updating for the particular feature I’m working on, and then right-clicking and getting Properties on the page I want to update. Next, armed with the five-digit number that the HTML file is named, I do a search in the AuthorIT database to find that exact topic, and then make my edits. Whew.

One incorrect assumption I had going in to the AuthorIT environment was that editing is all based in Microsoft Word. Not true at all, my AIT trainer protests, the editor is AIT’s own, but AIT does a good job of outputting to Word formats and you can use VB macros to format the output as you wish. I’m still learning so I’ll let you know what other incorrect assumptions I’m finding otherwise about.

The other thing that strikes me right away is that while it’s topic-based and structured authoring, all the things you create are either books or sub-books. I wonder if that interface could be changed to refer to deliverables or some other such generic term that isn’t loaded with a print connotation. It’s a minor nit to pick, that the loaded term “book” is so prevalent, but many other editors and CMSes have gone beyond the book terminology so I was surprised it still lives in AuthorIT.

To be perfectly honest, I wasn’t all that impressed with the available outputs. Here’s the list from the AuthorIT website: (hey, I would have given you all a more precise link, but when I clicked Publishable Outputs in the sidebar in that page, I got a page not found error using IE 7 on WinXP SP2.)

Publishable Outputs

Print

  • Printed Documentation (Word, RTF, or PDF)

Help

  • WinHelp
  • Microsoft HTML Help
  • Sun JavaHelp
  • Oracle Help for Java
  • Vista Help (Upon Release)

Web

  • Web and browser based Help
  • HTML 4.01 + CSS (W3C Validated)
  • XHTML 1.0 + CSS (W3C Validated)

Presentation

  • HTML based slide show Presentations

XML

  • XML
  • DITA

The first omission that comes to mind is the lack of Eclipse help output. There’s also no Flash help output. In addition, I wanted to analyze further on the usability and look and feel of the Web and browser based help, especially with the recent article complaining about DITA’s lack of a cross-browser “Web help” like what Robohelp outputs as well as the lack of FlashHelp output. There are a couple of good articles out lately about it. There’s an article on ditausers.org comparing Help Authoring Toolkits to the DITA Open Toolkit. His output comparison matrix for DITA points out the lack of a webhelp equivalent for DITA Open Toolkit transforms. Here’s Tony Self’s recent analysis on Writer’s UA website. But I’m not talking about DITA necessarily, unless I was going to propose outputting AuthorIT to DITA and using DITA transforms for publishing, a workflow that I’m not proposing because it just seems too roundabout and more difficult to automate.

Anyway, my first glance at the AuthorIT web help output is that it’s a little bit antiquated but it is tripane and it does have contents and index tabs but no search tab according to the demo on the AuthorIT site. Frankly, without a search function, no help system is complete. With a quick Google search, though, I learned from Char James-Tanny that “by default, AuthorIT does not include a search tab, although the Help file does include instructions for hooking up a free CGI search.” That article appears to be dated January 2003 so I would have to do more hands-on testing to determine the quality of the search and the ease to implement it. Interestingly, in that article she mentions using AuthorIT as the CMS and editing environment and then using RoboHelp for the more feature-rich output engine. I wonder if that’s still a viable toolkit and publishing engine combination now that Adobe is developing RoboHelp.

Writing an article like this one while I’m still very inexperienced with AuthorIT is risky because I will read it later and think, “why would I proclaim my ignorance in a public manner?” But I believe it’s important to capture initial thoughts and reactions while they’re fresh in my mind. So bear with me while I analzye the authoring system and the publishing system and draw some perhaps premature or immature conclusions.

blogging

Technical details of feed and blog set up

Last week I got an email asking me if I had taken over someone else’s blog since WordPress.com had a slight problem with feed glitches. Eep, I did nothing of the sort. But then I got a second comment asking if I was aware that the talk.bmc feed now gives justwriteclick.com content, and I realized that I hadn’t ever explained to all my previous subscribers on the talk.bmc feed that the feed now goes to my new justwriteclick.com blog. Sorry about that!

If you’re subscribed to http://feeds.feedburner.com/TalkBMC-AnneGentle, you’re now subscribed to the content on my justwriteclick.com blog. You can delete that subscription and subscribe to the new feed at http://feeds.feedburner.com/justwriteclick so that you’ll continue to get content updates when the old feed goes away eventually. I’m working with Feedburner technical support to get an official rollover to occur. Apparently people do this type of blog transfer quite often as they weren’t surprised by my request.

Ideally you don’t have to do anything (unless you’ve subscribed to both and are now annoyed by the double-content push, and if that’s the case, unsubscribe from the talk.bmc feed).  I appreciate you sticking with me and reading my blog, always. Let me know your suggestions and questions and I’ll do my best to address them. In another blog entry I’ll talk about URL redirects and domain name registrations, which have been easy with Google Applications and WordPress.com, plus fun to learn.

work

First work week round up

My employer, ASI, gives employees three hours a month to use to do volunteer work of your choice, and I’m busy thinking up ways to use that time. After Hurricane Katrina, I spent a half day at the Capitol Area Food Bank, using some hours that BMC gave to employees to spend their time helping Katrina evacuees. In a half day, four of us processed 8,400 pounds of food which can make 6,720 meals. So I might try to do that work again. It was interesting and I learned a lot. I’d also like helping out kids or parents, so I may investigate areas where the local school districts use volunteers. I also like that our local NPR station, kut.org, has a Get involved page.

Working at a company that enables non-profits has really made me want to learn about our users and how non-profits work. I found this game online called Karma Tycoon, where you run your own non-profit. It looks like it’s sponsered by Chase. Also interesting reading lately has been about non-profits in Second Life. I haven’t tried Second Life yet, mostly due to lack of time (I’d rather be blogging).

So if you’re knowledgeable about non-profits, membership management, church organizations, and so forth, let me know of websites and books that you find useful. And if you have good ideas for three hours a month of time spent volunteering near Austin, TX, let me know. I’ll keep you posted on my efforts.

Twitter or Pownce or Jaiku use cases – what can you do with Twitter?

I had a hard time coming up with a good reason to sign up for Twitter. But encouragement from whurley and all the press from SXSW Interactive 2007 (San Fran Gate, Slate, NYTimes)  made me sign up out of curiousity. I haven’t touched Pownce or Jaiku, and while I had heard about Dodgeball, I had no use for its Shout feature, all of which are similar feature sets to Twitter.

Now, I’m not a big text messager on my cell phone, but I do love Instant Messaging. My initial take on these services is that the point of Twitter and other microblog services is to allow text messaging of one person to many people at once using SMS or instant messaging as the sending or receiving device. It’s pushing one message to many, one status to many, and the receiver can determine how they want to receive the messages (web only, IM, or on their mobile device like the BlackJack or iPhone.)

So I went out looking for innovative uses for these microblog services. I submit this list and would love to keep adding to it.

  1. Really Simple Voting Poll tool as described by James Governor.
  2. Babysitter, nanny, or SAHP updates – parent or babysitter or nanny writes updates on what the baby ate, drank, or how long he or she napped as well as diaper status. Baby telemetry via SMS like The Trixie Tracker. I can’t find a specific example of someone using it for this purpose, though. I would mark those private as a parent.  
  3. Ultimate online or offline status indicator: “Rather than having to change your status on your IM, make a call to your colleague or family, making a blog post or sending several one line emails, with Twitter you can let everyone know exactly what you’re doing with a single 140 character message.” says Robin Good. Tons of examples of this. How about a search for the phrase “going to the store” to examine some examples.
  4. Microblogging: “it is much faster as writing a blog post, as fast as an sms or IM” says Loic Le Meur. I like the founder of Obvious, who made Twitter, Evan Williams’ twitter page as an example of a microblog at http://twitter.com/ev.
  5. Shopping, the original business plan for all the web stuff. I think  twitter.com/woot is the especially best example.
  6. News updates and conference coverage. Check out http://twitter.com/googlenews or http://twitter.com/cnn.
  7. Event updates or invites or general activity management like “who wants breakfast tacos?”
  8. Mini updates to your blog with a Twitter window as a side widget on your blog page, allowing you to do updates while you’re out and about. Barganista has an excellent use case. Really, it helps you write anything you need to remind yourself or someone else of but you’re not near a computer and only have your phone with you. Think of a To Do List that you can continue to post to.
  9. Friendsourcing as described on lifehack.org - asking your friends list for the best plumber, house inspector, or web designer that they know of (or are themselves).
  10. Get geographical by fine tuning your twitter reads to local items. Find an Austin-based weather updater to follow, favorite area sports teams updates like the Round Rock Express and the University of Texas sports scores (although I can only find http://twitter.com/espn which is not local), and an Austin local news feed (http://twitter.com/statesman).
  11. Integrate Twitter as a cost-free SMS gateway into your own applications as Monitwitter has done.
wiki

Contributing to wikis as a technical writer

I’ve been researching an article for STC Intercom about wikis and technical documentation as discussed in my previous post. In about two years of my interest in the topic, I have only discovered a handful of examples of wikis used for end-user documentation for a technical product. And sometimes I even stretched the term “technical product” to include all of eBay. Heh.

If you’re also interested in wiki research, I have also been compiling bookmarks of blogs or websites that comment on wiki use on del.icio.us too at http://del.icio.us/annegentle/wiki.

Anyway, here’s a list of the ones I’ve found as good examples so far, but my criteria are loose and fast, such as recognizable products or geeky products. I’m sure there are more, and this list of the top 57 wikis based on popularity offers an even longer list.

But instead of soliciting more examples, I want to ask a few more questions myself. How many of these wikis would I use to get an answer to a question? Probably all of them. Now, how many wikis have I contributed to? How about you? If you haven’t ever contributed to a wiki, why not? If you have, tell us which one, and what motivated you to contribute?

talk.bmc

Microdecisions and macrodecisions

My final post at talk.bmc, but stay tuned at www.justwriteclick.com for more blogging

I like to think about each day as a series of microdecisions, and hope that I mostly make microdecisions that make my kids and my family a priority. And eventually it won’t be the kids schedule we’re balancing, but maybe it’ll be the awesome backyard landscaping and garden plans. Or a boat at a lake cottage that needs to be restored.

What is a microdecision? It could be the decisions that are mundane and every day. Or it might be a decision that you make in a reactive manner, quickly and reflexively. An example of a mundane microdecision is, “Do I work past 5:30 or do I head home and start a healthy dinner for my family so when my husband walks in the door after picking up two kids and driving for 45 minutes, it smells like a decent meal is ready?” Some days that’s a split second microdecision. Decide to stay and get a bit more work done, or go home to get a good start on the evening?

There are decisions that I consider to be in between micro and macro, such as the time I was in an important set of all-day meetings to work on user roles that will be using our new XML editor and CMS system for our move to DITA. I got a phone call from my husband who had graciously prioritized my meetings over his work schedule and taken our 3-year-old to the doctor because he was limping and complaining that his leg hurt after a tumble on his tricycle in our driveway. Sure enough, our son needed Xrays and I decided that I had to leave the meetings in order to be there for the both while he waited for the Xrays. Since I was 34 weeks pregnant at the time, I couldn’t go into the Xray room with my son, but at least I could entertain him in the waiting room and be there when he was done.

These situations are the type of decisions you’re faced with as a working parent. I’m incredibly fortunate to have a husband who’s a true partner in raising kids and is willing to trade priorities with me while making his microdecisions also.

But there comes a time when a macrodecision comes up. In my case, I was offered an exciting new job with the additional bonus of a 30-hour work week with full benefits. Plus the job is at a company that is doing structured authoring and offers customer relationship management and lots of other infrastructure for member management, even social media for their users, who are busy running professional organizations like the STC. See the Advanced Solutions website for more information.

I’m the kind of working mom who wants to love her work and at the end of the work day, face my kids and say, “Mom did cool stuff at work today!” So this macrodecision made perfect sense when I prioritized both my kids and being able to communicate my own excitement about the work to be done.

BMC has offered me so many neat opportunities and writing for this blog is just one of the tasks that I will miss here. But I have started blogging at www.justwriteclick.com and I hope you will subscribe to that feed and continue the conversation there.