Monthly Archives: April 2007

talk.bmc

A whole new way to look at book maps

Nope, not DITA book maps for once. Instead, maps of locations mentioned in a book.

How neat is this – Google Books lets you visualize the places mentioned in a fiction book in a map. For example, The Travels of Marco Polo becomes so much more real when you see a visual map of the locations he visited. Scroll down on the Google About Book page to see the map.

Who wouldn’t want to be a kid writing a book report in this day and age? Kiev, Venice, and Genoa, to name a few, with page number references for the book, and marked locations on a map. Click on the red pushpins to get an in-context excerpt of where the location is mentioned in the book and a page number.

I found this on the “Inside Google Book Search” blog at http://booksearch.blogspot.com/2007/01/books-mapped.html. I first heard about the Google Book project at SXSW 2005, in a panel session called “Book Digitisation And The Revenge Of The Librarians.” This blog entry on a blog called Innovation Eye does a great job of summarizing all the interesting discussion that went on between the panel members and audience members.

talk.bmc

Wikis for technical documentation, one writer’s story

An interview with Emily Kaplan, a technical writer and former co-worker of mine, who maintains a wiki for Motorola

A good friend of mine, Emily Kaplan, was kind enough to let me interview her via email to find out more about her experience with managing a wiki for technical documentation. She writes for the Motorola Q phone. Back in November of last year, just in time for holiday shoppers, the Motorola Q was on the cover of October’s Wired Magazine special issue (Wired Test). Here’s the article: http://wired.com/wired/archive/14.10/play.html?pg=14. Here’s a link to the Q wiki: http://www.motoqwiki.com/index.php?title=Motorola_Q_Wiki. An excellent starter reference page is found at http://www.motoqwiki.com/index.php?title=Motorola_Q_Wiki:About

Emily says “I’m a senior technical writer contracting with Motorola. My group has about six writers, an editor, and a graphic artist. We’re spread across state and national lines in Illinois, Florida, and the U.K. We write user’s guides for the high profile mobile phones that you see everywhere. (We have a sister group that produces the in-device help and videos.) I go to the office once a week and work from my house the rest the of the week in my pajamas.”

Here are the questions I asked her, along with the answers. I am trying to find out more about real experiences with wikis for technical documentation. The concept of wikis for technical documentation and user-created content was mentioned recently at the Writer’s User Assistance conference as the future of online help systems in the session “User Assistance Trends Panel: What’s Ripe, Hype, and Out-of-sight.” The panel consisted of Rob Houser, Dana Chisnell, Paul Mueller, Bernard Aschwanden, and Joe Welinske. By learning from others experiences, perhaps we can avoid pitfalls or craft best practices.

Anne: What types of information (concept, task, or reference) goes on the wiki, and did you pre-populate the wiki with certain basic information?

Emily: The foundation for the MOTO Q wiki was the user’s guide, which has mostly tasks and some reference types of info., such as diagrams of the keypad and how to insert a memory card, etc.

Anne: What are the main goals for the wiki – customer support, customers making connections on their own, community building, or using it as another way to publish information that customers can get elsewhere?

Emily: The main goal of the wiki was to provide customer support. Some users lose their manuals or don’t keep them or want to learn the latest details that might not be in their manuals if they have upgraded their software. Secondarily, customers can share information, which builds a sense of community. Not as much as a blog or user forum, but a little.

Anne: What type of maintenance do you perform on the wiki?

Emily: So far, I’ve had to do a product name change and also add new sections as new features have been developed. I do not touch any customer input, and we haven’t had to deal with malicious users.

Anne: Does wiki maintenance require more work on navigation or on content?

Emily: I haven’t touched navigation at all, only content.

Anne: Have you discovered a core group of users taking the wiki content under their wing?

Emily: We have two users who regularly add information for Verizon-flavored phones. Other user-based sites for this phone exist already, so they might be going there instead.

Anne: What feedback have you received from customers, if any?

Emily: I haven’t been involved with user feedback for the wiki.

Anne: Was there a customer request for a wiki or did the business decide to do this on their own?

Emily: One person in the marketing group spearheaded the idea. There wasn’t a customer request because it was a brand new product, but the type of product (a computer-like phone) suggested that the average user might be more web savvy than for other phones, so it was a natural thought progression.

Anne: What is the business justification for building the wiki?

Emily: It’s fast, cheap, and easy to maintain. And it reaches potentially millions of users. Like everyone else, we’re trying to reduce paper docs, and this is one attempt…

Anne: What underlying technology does the wiki use? MediaWiki? (That’s what it looks like to me, anyway.)

Emily: It is indeed MediaWiki. It also uses a SQL database in the backend for some user information.

And a bonus question/answer!

One of the downsides of the wiki that we haven’t been able to address yet is that we have many flavors of the MOTO Q phone coming out. These are phones that have totally different keypads and some unique features. We haven’t figured out how to reuse the info. or if we even want to create more wikis. (We’re talking 7 or 8 varieties right now.) Anyway, a dilemma…

At BMC, we do have user-generated content and are always looking for more ways to connect fellow BMC product experts. We have forums on BMC DevCon as one place for expert users to share advice, tips, tricks, and so forth with others. And, you can ask other users questions there, and our support staff chimes in as well. AR System has had an active developer community for years and the current site can be found at http://www.bmc.com/arsystem/dev_community/. TalkBMC is yet another place for us to connect with users, and give users the chance to let us know their experiences, and hopefully offer advice as well.

What do you think of wikis for technical documentation? Would you like contributing what you know? Let us know.

talk.bmc

Transforming coins into donations using technology

I’m impressed when technology is used to transfer loose change into donations to charity

I’m in the Sunnyvale BMC office this week, and I’m learning a lot about Configuration Management and how IT departments can manage desktops and servers, automatically sending patches and updates. I’m trying to put myself in the role of an IT system administrator and figure out the best applications of information technology for business purposes.

One innovative application of IT that I noticed recently was that you can turn your loose change into about anything you want using automated kiosks. Coinstar machines are used in the U.S. as a convenient way to donate for charity. While their corporate headquarters are in Bellevue, Washington, Coinstar kiosks were first installed in the San Francisco Bay area, according to their Frequently Asked Questions page. Automated coin counting and tallying technology is applied to turn coins into other things like donations or Amazon gift cards. They have grown from processing $200,000 per year in 1997 to more than $3 million in 2004 and reached $20 million in 2006.

To me, this is a great application of already existing technology to raise money where it’s needed. It also gets money circulating again that might have stayed in a coffee can in your house for a long time. Coinstar estimates that American households contain about $10.5 billion in uncounted change. I doubt my house contains even $50 worth of loose change, but then again, I haven’t overturned the couch cushions in a while. But there are certainly people who like to collect their loose change in one location and then find it’s quite unweilding to use to spend on something.

Now, I know there is a basic concept of money for services or products. But coins are getting turned in gift certificates, charitable donations, and even pre-paid wireless minutes. That transformation is really cool to me.

Coinstar has even applied more technology on top of their patented technology by using Geographic Information System (GIS) technology to help them figure out where to place kiosks to collect the most change so they can predict performance based on placement. I have no idea how their maps know who is most likely to bring in a bucket of change, but there you go. Using information technology to help others while decluttering at the same time. That’s a neat system to me, and a great application of technology.

talk.bmc

Getting Started with DITA

A brief overview for a couple of fellow Austin writers who have asked me recently how and where to get started with DITA

I have gotten two similar questions about getting started with DITA in the time span of about two weeks, so I thought I’d borrow from some of my answers as a write-up for a blog post. One person wants to ditch her Adobe toolset in frustration and try out some DITA workflows with all free tools. The other is a lone writer in a small shop and wants to find out more about DITA and see if it might work well in her Agile development environment. While I’m a huge DITA advocate and see many ways that DITA can help with many doc goals, I don’t think that DITA has all the answers necessarily. Topic-based authoring with just concept, task, and reference types is a different mind set for both writing and publishing. But, you could certainly put together a toolkit of freebies with DITA to try it on for size. So here are some starting points.

Get very familiar with topic-oriented writing

Without some up-front information architecture and design where you really analyze your documentation needs, and figure out what task, concept, and reference means for your body of work, DITA won’t help you. Transforming legacy information into topics may or may not be a worthwhile effort so some up front analysis will help you.

Bare minimum tool set to “do” DITA

You’ll need the DITA Open Toolkit, available at http://sourceforge.net/project/showfiles.php?group_id=132728. Here are direct links for the 1.3 package that you just download and unpackage on your hard drive. Windows zip Linux tarball

These full packages of the DITA Open Toolkit contain all the sub-tools that you need for full evaluation from authoring to building output. Most of these tools require the Java Platform, so, Java is a prerequisite to using the DITA Open Toolkit. Download and install the Java Platform Standard Edition (SE) 5.0, available at http://java.sun.com/j2se/index.jsp.

Ant 1.6.5 runs automatic builds on your DITA maps, and the DITA Open Toolkit gives you ant scripts for builds already.
Xalan-J 2.6 is an XSLT processor which is required to run the transforms.
FOP 0.20.5 is needed for PDF output. (Note: For compiled HTML help (CHM) you’ll need the HTML Help Workshop, which isn’t included in the Open toolkit, but most help authors will already have this installed.)
ICU4J 3.3.4 is included for improved NLS-enabled index sorting.
Apache Catalog Resolver 1.1 is a standard XML catalog mechanism.

Plus, the newest full package (1.3) contains a startcmd batch file in the root folder that you can use to set up your environment each time you run the DITA Open Toolkit. Considering what headaches I had just with environment variables in Windows, I am greatly appreciative of this little batch file.

If you want to first just look at topics and create some output before authoring anything of your own, look at the EvaluateOT.html file in the root directory of your DITA Open Toolkit install. Double-click the startcmd.bat file, then type ant samples.web -f build_demo.xml at the command line and you will have your first set of DITA output in a newly-created \out folder in your DITA Open Toolkit installation folder.

When you want to create your own topics and maps, you’ll need an XML editor. While you can certainly edit DITA XML in Notepad, you’re going to want a validating XML editor for serious authoring and evaluation. See my suggestions next.

DITA XML Editors

Previously I posted my notes from Don Day’s talk at the Central Texas DITA User’s Group about evaluating DITA editors: http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-editor-eval. Now, the next step for me is to start naming names. Let me be clear, though, since I’ve been on maternity leave for the last six months or so, I haven’t been seriously evaluating XML editors for BMC. Others are doing that and I’ll be happy to use whatever they recommend for our environment. But, for my friends who have been asking me about DITA, let’s break this evaluation into free and not-so-free. Note: nearly all enterprise-level XML editors have 30-day trials, but it’s tough to get enough done in a 30-day evaluation of DITA and the XML editor if you’re just starting out with topics and DITA.

Awareness of DITA is not always an easy achievement, apparently, and when you’re new to DITA, it’s tough to evaluate “DITA aware.” So I guess you just need to trust others when they say an editor is a DITA aware editor.

Free XML editors

XML Copy Editor – this open source project has an XML editor that claims to support DITA. https://sourceforge.net/projects/xml-copy-editor/

DITA Storm – this is a free web-based DITA editor. You can either install it yourself if you have a web server, or try out the ditausers.org online web-based editor for free (use the coupon code BETA) during the evaluation period.

Enterprise-level XML editors (with 30-day free trials)

I believe that you should convince your manager you need this level of editor if you’re serious about writing DITA topics for end-user doc.

Bob Doyle has done an excellent job of evaluating XML editors in this article, X Marks the Spot: Let’s Take Today’s XML Content-Creation Tools for a Spin, complete with tables of prices, platforms, support info, all the specs you’d need to evaluate a tool for your environment. The ones I have installed and tried are: Adobe FrameMaker ($799), Arbortext Editor ($695), XMetaL Author DITA Edition ($895), and Syntext Serna ($195). You would have to determine what’s right for your particular environment and preferences.

What to do to start writing DITA topics

Open your XML editor and start with either a concept, task, or reference topic type. Or even start with a topic to begin with. Write some content, and validate it as you go. Once you get a handful of topics, make a DITA map either using the code in an XML editor or using a DITA Map editor like the Task Modeler available as an Eclipse plug-in.

What to do to get output from your DITA topics

You can modify the ant scripts provided with the DITA Open Toolkit for your own builds. I was able to do a few ant scripts just based on the template files and examples the toolkit provides. I used the “ant/ sample_htmlhelp.xml” template to make this build file for my map file named processfile.ditamap on Windows. Edited: to link to the sample build file code instead of posting it here because apparently our DIV layout doesn’t like wide-width PRE areas in the middle column. :)

Nice-to-have tools for anything beyond just evaluation

You’ll want to automate building output with Ant. The example build file above gives you a start, and there are plenty of templates provided in the Toolkit.

Once you think about enterprise publishing, reusing topics across groups, and so on, you’ll want to use a Content Management System. I think CMS tools for DITA is an entirely different topic that deserves more research so I won’t say more than that yet. To get started on larger doc sets without a CMS, use a logical folder structure and defined file naming conventions, then use the OS search tools to look for metadata within topics.

A DITA map editor that either integrates with the CMS or the free Task Modeler from IBM has a really good visual method for editing DITA maps.

More reading

I like the Introduction to DITA: A User Guide to the Darwin Information Typing Architecture book available here.

The DITA Open Toolkit User Guide and Reference is very useful as well, and free.

Bob Doyle, an active member of the Boston DITA User’s Group, also has a helpful article in the E Content Magazine column, I Column Like I CM: Getting Started with DITA.

Use Don Day’s evaluation heuristic for editors if you want to do a full-blown evaluation for your preferences in an authoring tool.

Everyone must read Scott Abel’s article, 10 DITA Lessons Learned From the Trenches on the Content Wrangler when evaluating DITA for their doc needs.

Anyway, once you get very far with the DITA Open Toolkit you might fall back in love with the Adobe toolkit. I’d love to hear just how far you get and whether you fall in love.

talk.bmc

Checking out the new DITA Users website

Using a coupon code (it’s BETA) I joined the new DITA Users website for free today

I was looking at DITA Storm, the web-based DITA editor, for a side project today and came across a link touting “comprehensive project-level DITA authoring and publishing experience.” I’m pretty excited about this discovery — it’s ditausers.org, a place where I can try out the web-based DITA editor on a hosted web server. And, it’s free membership right now with reasonable rates later. The coupon code is BETA, just go through the checkout system and use Coupon as your method of payment. Nifty!

As for my dabblings with DITA Storm itself, I couldn’t convince my home system administrator (my husband) to help me install it on our webserver at home. Our Apache installation would have to be upgraded (one method of implementing DITA Storm needs an Apache Web Server extension that includes PHP with XSL such as Sablotron) and I don’t blame him for turning down that work request. I didn’t want to do the upgrade myself either. DITA Users has the right idea of installing the web server for you if you just want to author and publish DITA with little backend work yourself.

DITA Storm always gets me thinking about what’s next for web-browser editors and DITA. I wonder if a concept of a DITA audit is ready for prime time? You know how you can upload and validate your HTML documents to test forW3C Recommendations compliance, or 508 accessibility problems, such as the W3C HTML Validation Service and others like it (see this list). I think that some day writers might want to upload their DITA marked up documents to test for best practices in tagging for their topics, especially for task. I believe that IBM has CSS files that automatically check on how well “typed” certain content is after going through their migration tool. For example, are ordered lists in a generic topic and should be re-written as tasks with <step><cmd> elements? Is a validation step the next thing for making sure you’re using DITA to its fullest potential?

I plan to put the feed for the DITA Users Progress blog in my feed reader list. Thanks for the free beta membership, guys!

talk.bmc

Tech writers are blogging and podcasting

There are a bunch of new tech writing-related blogs and podcasters that I’m excited to see

Since I’ve been away on maternity leave since October 2006, I missed the arrival of techwritervoices.com,, all podcasts related to technical writing topics. Very exciting stuff, birthed the same month as my new baby! I had already stumbled across a blog entry on a site called Monkey Pi depicting controversy where they referred to the podcast with Mike Hamilton of MadCap Software on Tech Writer Voices. I won’t jump into the comments section there since I don’t use RoboHelp or Flare for a Help Authoring Tool. But podcasts are a great way to get your story heard if this discussion is any indication.

This week one STC president candidate used the techwritervoices.com site to campaign for her election. One feature that is so great about this podcast blog is that they have collections of links that were discussed during the podcast, making for easy perusal and perhaps valuable link gold. I’m certainly intrigued and impressed at their dedication to podcasting as a means to communicate about technical writing topics.

One of the writers and podcasters of the techwritervoices.com site, Tom Johnson, writes about work-family balance and how listening to podcasts during commutes helps him keep up. Another reader said that she found it helped her stay current while taking time off to raise young kids (an ongoing task on both counts!) While I don’t have a long enough commute (just 8 minutes) to listen to lots of podcasts, I like the idea of staying current by listening as well as reading. Pretty neat.

I also just made the connection that Tom Johnson had asked the Austin chapter about blogging software last year when we started a blog as a substitute for our chapter newsletter. Our STC chapter blog is at http://stcaustin.blogspot.com/. I think the personal connections are a big part of blogging and our little corner of the blogging world is no exception.

I’m also reading this thread about blogging on the STC Forums with interest. I especially appreciate Scott Abel’s testimony about how blogging has changed his professional potential greatly. His enthusiasm for structured blogging makes me want to install WordPress or Moveable Type on my home server and get that structured blogging plug-in working!

There are many ways that tech writers are embracing podcasting and blogging as a means of communicating with other like-minded colleagues. I’d like to see how we take the next step to communicate technical topics to our end-users. Of course, every post that I write where I talk about technical communication instead of actually communicating about BMC products proves I have a comfort level with information design and I feel I’m still on the learning curve with information technology topics. But I plan to write a lot about my new product assignment, BMC Configuration Management, formerly named Marimba, over the next few weeks.

Ynema, our talk.bmc.com producer, gets credit for interviewing a tech writer early on with my podcast from last year. Y, you early adopter, you. She is doing amazing work with video as well and I’m very excited to see the new things she is producing here. Maybe we can come up with a screencast about the BMC products I’m learning about and share with you all.