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.

Sewing is technology

While on maternity leave, I picked up again on the hobbies that I enjoy that are, well, decidedly feminine but have quite an edge of technology to them. For example, sewing involves a rather complicated machine and patterns and an ability to envision things in three dimensions and reverse and inside out and so on. There is a lot of engineering ability in sewing and other crafts like knitting. Technology geekery and crafting have an intersection on websites like Craft magazine at craftzine.com, I’d call it a “sister” publication to Make magazine. Shows like Knitty Gritty, hosted by an Austinite, also showcase the hipness of knitting.

Back in March on The View, Rosie O’Donnell said that she was using eBay to buy a sewing machine from the 70s just like the one that she learned on as a girl because trying to learn a new machine was just too frustrating. I imagine there are other examples of technology that is relatively unchanged through the years, but where else but in the world of sewing can you find machines that still work exactly as they used to more than 30 years ago? I no longer have the machine I learned on, but I can identify with Rosie’s dilemma. Fortunately I was given a rather fancy used machine from my mom the amazing quilter. It is quite high-tech as sewing machines go, and I constantly refer to the manual since it has programmable stitching and requires interchangeable feet for different stiches. But the basics are still familiar, such as threading the upper thread, preparing the bobbin thread, and getting the bobbin thread to come up through the bottom of the machine – all these are very similar to the two other machines I’ve ever used. So when Rosie said that she couldn’t even figure out the bobbin for a new sewing machine that she bought for her daughter, I had to agree with her decision to buy the old tried and trusted machine of her youth on eBay.

To me, the technical writing involved in sewing and patterns is a fascinating subject. In fact, Katherine Durack, one of the technical communications professors at Miami University (where I went to graduate school) published a paper in 1997 about sewing patterns and their history through the years titled, “Patterns for Success: A Lesson In Usable Design from U.S. Patent Records.” Really interesting stuff. Here’s the abstract: Investigates the design history of women’s household sewing patterns as that history is recorded in United States Patent Records. Finds that the history of home sewing patterns illustrates a key aspect of usable design: the interrelationship between a device and its documentation and the way changes to both enhance overall product usability.

While mostly women sew as a hobby, I think the car makeover shows are giving young boys a good look at a potential career in reupholstering car seats and the like. We have a framed appliquéd picture in my son’s room that my husband did when he was a boy, in fact, so I know the art and craft and technology of sewing won’t be lost on my boys. And the lessons learned from sewing transfer easily to other engineering projects, I believe. So time spent learning to sew is time well spent in preparation for other scientific and technological endeavors.

This post describes creating a watched folder that runs DITA transforms on content that is copied into the folder on a shared server. It also gives instructions for using this “transform engine” to output both PDF and CHM files using the default DITA Open Toolkit transform files. I devised this set up so that we could test our prototypes while we model our existing content, and I wanted to share it with others who are getting started with DITA on a small scale.

Now for the disclaimers! To many, reading my batch file coding will be like watching amateur mic night at an improv comedy club, but I welcome suggestions and improvements to this system. I offer it without warranty and fully disclose that the batch files actually delete files on your system (in a space-saving effort) and may very well fill up your hard drive with generated PDF and CHM files. So don’t say I didn’t warn you! I tell you, use at your own risk.

Now that I’ve disclaimed appropriately, I want to say that I think it offers a bootstrap automation effort for DITA builds and I wanted to give it out in case it helps others.

Prerequisites

Ensure that WinZip can be run within a batch file (command line).
The batch files for the server-based transform engine call WinZip using DOS commands. In order to ensure that the version of WinZip that the server is using supports command-line calls, download and install the Winzip Command Line Support Plug-In from this link.

Ensure that the DITA Open Toolkit works properly

The DITA Open Toolkit must be installed and running correctly on a Windows computer by installing all the pre-requisites and testing transforms. Refer to the documentation accompanying the DITA Open Toolkit to meet this prerequisite. Basically, you’ll need the DITA Open Toolkit, available at http://sourceforge.net/project/showfiles.php?group_id=132728. Download and unpackage the zip on your hard drive. The 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.

Ensure that the Idiom Plug-in works properly

To run PDF2 transforms, follow these instructions to install the pre-requisites for it and install the plug-in itself. http://dita-ot.sourceforge.net/doc/ot-userguide13/xhtml/plugins/installing_fo.html. For some reason, this detailed-level topic has been eliminated from the 1.3.1 documentation, and I couldn’t find another detailed installation topic like this one, so, that’s why I’m linking to an outdated topic in the DITA Open Toolkit.

Download the bootstrap automation files

Download this zip of batch files, ant files, and a custom css file that make up the “transform engine.” The “engine” consists of five batch files and three Ant build files. They are currently set to work in a DITA-base directory named c:\DITA-OT1.3.1 but you can rename the DITA-base directory as needed.

Installing the transform engine on a shared server

1. In the DITA Open Toolkit working directory, create a dita_in directory. For example, c:\dita-ot\dita_in.
2. Unzip the batch files and Ant build files into the <dita-ot>\dita_in directory.
3. Unzip the CSS file into the <dita-ot>\css directory.
4. Edit the files if needed to match your directory structure. For example, the DITA working directory is set to C:\DITA-OT1.3.1 and you might need to change that in every file to match your environment.
5. Enable sharing for the dita_in folder.
6. In the DITA Open Toolkit working directory, create a dita_out directory.
7. Enable sharing for the dita_out folder.
8. Copy the bmc_dita_chm.css file to the DITA Open Toolkit working directory in the css directory, for example C:\DITA-OT1.3.1\css. The ant CHM build file uses this CSS file to substitute a Verdana-font-based CSS file instead of the default DITA CSS.
9. Create a Windows Scheduled Task to run the dita_in\buildDITA.bat file every 10 minutes.

Submitting DITA maps to be transformed

1. Place all topic files, graphics files, and the ditamap file in a folder, ensuring that the map file has the .ditamap extension and is in the root directory.
2. Zip the folder into a zip file. Be sure to check the Save full path info option.
   You can name the zip file anything.
3. Copy the zip file into the \\serverName\dita_in folder.
   The next time the buildDITA.bat scheduled task starts, it will kick off the transforms.
4. Wait at least 10-12 minutes for the transform to complete.
   Note: The transform itself should not take this long, but the timing of the watched batch file to run is scheduled on 10 minute intervals.
5. Once the transforms are complete, copy the PDF and CHM files from the \\serverName\dita_out\htmlhelp and \\serverName\dita_out\pdf or \pdf2 folders.Thanks to the renameOutputFiles.bat batch file, the file names will have a time/date stamp with the following notation: yymmdd_hhmmss.pdf. Example: 052507_101540.pdf. Also, extra files that are generated during the transform are deleted with this batch file, so you can modify that batch file if you want to keep dita.list and other precursor files.

That’s all there is to it. Please let me know your feedback and suggestions for improvement.

While on maternity leave, I read through the lengthy and informative What’s New in Adobe RoboHelp 6? even though I don’t use RoboHelp. I like to follow Adobe’s treatment of tech pub tools though.

I suppose if I had to pick favorite new features, one would be the Command line compiling for help projects. I do love batch files, and scheduling help builds automatically would be great.

I especially love Rob’s “Emotional Comments” paragraph towards the end of the review. To quote: “Like many of you, I have had my ups and downs with RoboHelp. I’ve enjoyed working with the tool for a long time. (Well, at least since they worked out most of the bugs in the first seven releases.) I was surprised and disappointed at the complete lack of interest demonstrated to our industry by Macromedia. And I remain cautiously optimistic that Adobe will invigorate the technical communication community with its newly created suite of tools (which include RoboHelp, Framemaker, Captivate, and Acrobat).”

This paragraph is actually the first mention I’ve read of the “newly created suite” of tools. I must go to the Adobe site now and read up on it… Okay, a quick Google search didn’t bring me to the Adobe site but brought me to the blog entries that speculate about such a suite. However, on the Adobe products page, there is a category for eLearning and technical communication products which is an excellent collection of tools.

I’ve also added the Adobe Technical Communication blog to my feed reader, a group blog where they’re keeping the rumors and speculation at bay by simply blogging about it. Way to go, Adobe. This blog is an excellent example ofhaving your product managers use a Web 2.0 communication tool like a blog to field questions and allay concerns.

Thanks for the link, Carla! Take a look at the visual thesaurus at http://www.visualthesaurus.com/.

Enter a word and it shows synonyms with lines, and antonyms with dotted lines, plus when you put your mouse over a word a definition is displayed. And it offers audio pronunciation recordings. This tool is perfect for writers, and I’m sure has proven useful for teachers and English as a second language students.

I have a fascination with the “live” sites where you can visualize what’s going on across an entire site such as Twitter, Flickr, Digg, or Del.icio.us. It appears to be mostly for entertainment value, although I’m sure that researchers and journalists have these toolkits in their toolbelt when they need a fresh take on a story. I find it also sparks creative ideas or sends you along paths you never would have found otherwise.

Here are some of my favorites to watch. Check out the screenshots for a preview of what awaits behind the link. The map-based visualizations are enabled by Google Maps geo-developers, and they recently had a conferenced named “Where 2.0″ (great name).

• Twittervision – I managed to capture one from Austin, TX, while I too was hiding from the thunderstorms that were coming through. Since there’s often a rate of over 20 Twitters in the time period that this algorithm uses, I only tried a few times to capture one of my own twits. This is the 3D version with a glowing globe that spins around and then marks each twit. Very cool.
  
• Flickrvision – This is the classic view of the flat world map. This particular picture is of a chipmunk and I apologize for the poor screenshot quality but the layout that I’m confined to won’t like even this size of graphics, so I encourage you to click the Flickrvision link and see it for yourself.
  
• LiveMarks – This visualization lets you watch the bookmarks as they’re being added by all users of del.icio.us. One of the neatest visualizations that I believe was popularized by del.icio.us is tag clouds.
  
• Digg’s API contest winners for visualizations – This screen shows Digg Charts, which isn’t nearly as fun as the winner, Digg City, but it looks so much like a dashboard I had to include it. BSM Dashboard offers views not of popular stories but of high priority
  
• These aren’t “live” viewers, but TouchGraph offers neat visualizations of connections between objects, such as books or movies on Amazon, or connections between “web 2.0″ or major retailer’s websites via Google’s related links database.
  

Wow, I think we need these types of visualizations for all the connections that BMC’s products have because we have done so many integrations to get the BSM story just right. I suppose Topology Discovery has the closest match to these types of visualizations.

I’d better tear my eyes off of TwitterVision long enough to post this entry… what visualizations help you with your job lately?

IE 7 is installed on my home computer (but not my work computer) and I recently wanted to add the del.icio.us bookmarklet button using del.icio.us’s instructions. However, in IE7, there is no View Toolbar as the nice tutorial shows (http://del.icio.us/help/video/ielinks) (which was made using Wink, which I have used in the past to make tutorials as well!)

So, instead, I used Google Toolbar to add it to my Google Toolbar, which strikes me as slightly odd, but IE7’s Settings dialog box led me to the Google Toolbar easier than an IE method of adding a button on their toolbar. Here are the steps I used.

1. In IE 7, click Settings, and then click Options.
2. Click the Buttons tab on the Toolbar Options dialog box.
3. Click the Button Gallery Custom button and then click Add.
4. You’ll go to this website: http://toolbar.google.com/buttons/gallery?hl=en and then do a search for del.icio.us.

There were two available buttons when I looked. Choose one of the buttons and Hey Presto, add it to your Google Toolbar so that a little square button appears.

Now, next time you’re on a page that you want to add to your del.icio.us bookmarks, you click the button in the toolbar and fill out the webform with notes, a description, and tags. Neato.

I was asked recently about blogs or websites that discuss emerging technologies especially as related to IT and business service management. Now, when I hear the term “emergent technology” (Is emergent even a word?), the ones that come to mind immediately are engadget.com and gizmodo.com, but those are more for consumer products I’d say. There’s of course, Wired, but again that’s not necessarily related to managing desktops across a company or managing servers for accomplishing business tasks.

For some interesting reading, MIT has a Technology Review website but again, it’s all technology for all applications, not just for IT. Fascinating website, though. The list for 2007 is as follows:

• Peering into Video’s Future – The Internet is about to drown in digital video. Hui Zhang thinks peer-to-peer networks could come to the rescue.
• Nanocharging Solar – Arthur Nozik believes quantum-dot solar power could boost output in cheap photovoltaics.
• Neuron Control – Karl Deisseroth’s genetically engineered “light switch,” which lets scientists turn selected parts of the brain on and off, may help improve treatments for depression and other disorders.
• Nanohealing – Tiny fibers will save lives by stopping bleeding and aiding recovery from brain injury, says Rutledge Ellis-Behnke.
• Augmented Reality Markus Kähäri wants to superimpose digital information on the real world.
• Invisible Revolution Artificially structured metamaterials could transform telecommunications, data storage, and even solar energy, says David R. Smith.
• Digital Imaging, Reimagined Richard Baraniuk and Kevin Kelly believe compressive sensing could help devices such as cameras and medical scanners capture images more efficiently.
• Personalized Medical Monitors – John Guttag says using computers to automate some diagnostics could make medicine more personal.
• A New Focus for Light Kenneth Crozier and Federico Capasso have created light-focusing optical antennas that could lead to DVDs that hold hundreds of movies.
• Single-Cell Analysis Norman Dovichi believes that detecting minute differences between individual cells could improve medical tests and treatments.

Stephen O’Grady, the RedMonk analyst, tags several posts with Emerging Technologies so peruse the archives to your heart’s content. I especially enjoyed the post about Wikipedia being proposed as an aid to help the public prevent, slow and survive a deadly viral outbreak. Yeesh.

It seems that most of the categories for new technology are things like medical applications, travel applications, security, and personal technology. I would say that the concept of BSM itself is an emergent technology but it has matured beyond nascent for certain.

Advancements in security are certainly tied into corporate IT which is why I enjoy reading Jeff Bohren’s blog, The Identity Management Expert very much.

Are there other emerging technologies that solely relate to IT that I’ve missed?

In this month’s Central Texas DITA User Group meeting, we had an excellent presentation about linking using DITA maps and relationship tables by Scott Stark from IBM. He’s located in Austin and supports about 150 writers in California. His presentation is available for download from the Files section (membership required) of the ctdug Yahoo Group. When the video of the presentation is posted, I’ll be sure to link to that as well. In the Files section he also includes examples of the files he demonstrated with sibling or family links, sequential links (automating previous and next topic links), required links, target only or source only, and showed the power of linking that can be done with DITA automatically.

For even more information about the power of linking with relationship tables, Scott highly recommends Linking DITA Topics Through Relationship Tables by Kylene Bruski of Comtech Services, Inc.

What caught my attention this particular meeting is the de-emphasis on inline links, or links within the paragraph context as the text is read. This blog entry has many examples of inline links in the first two paragraphs. It’s not really topic-like. Scott stated that there are basically just three types of links in DITA – inline, citation, and related links. That is a precise summary. I believe that he most powerful portion of DITA and DITA maps are the management of related links. But I also believe that inline links have value as well, even in a topic-based system like DITA.

Inline links are what we are commonly finding as we continue to analyze our existing content. We have relied on cross-references in our FrameMaker documentation and online help to shorten tasks by having the first step link to another task, by collecting lists of cross-references to suggest what to do next, and for glossary definitions as popups within the text. We’re still trying to determine the best course of action for migrating those links.

While deliverables that contain lots of cross-references are not topic-oriented, I am starting to wonder if inline links are going to be the stage for usability battles to be waged because of sites like Wikipedia that heavily rely on inline linking for context. Since the user can probably safely assume that inline links in a help system go only to places within the information deliverable, the inline link offers valuable context to the reader and doesn’t “remove” the reader from the user assistance system. Also, placing related links at the bottom of a page where the reader has to scroll to in order to view might be another usability problem.

So, does DITA have it wrong when it comes to usability of links?

On Don Day’s suggestion, I did some searching for studies that would back up the topic-oriented link collection method that DITA advocates. According to this usability study titled Where Should You Put the Links? Comparing Embedded and Framed/Non-Framed Links, related links embedded on the left hand side of a screen layout were “searched faster (though not significantly), was perceived as being easier to navigate and to find information than the other link conditions.” I also found some excellent blog posts by SEO experts when trying to find usability studies to back the DITA preference for collecting links in one location. While SEO is more about optimizing pages for search than the actual readability of the page, there are excellent arguments back and forth for when you should use inline links and when they are actually a distraction. I first read “Inline Linking Bad for Usability” and I enjoyed his examples – one written with all inline links, and one written with all related links at the bottom. I would wonder if blogs with inline links and Wikipedia will “train” readers that inline links are helpful to click but perhaps only after they read the entire entry, our readers will be more able to perform their tasks despite inline links.

Another blog post by an SEO is on “The Value of Embedded Links” and one of his arguments is “So, regardless of where links are, chances may be that some visitors will miss links. Ideally, the way around that is to make sure that links within content can be easily seen.” I see this as a “scattershot” method, however, rather than analyzing your content and audience to determine the best placement of links, you would just place them everywhere you could, if you follow this argument to a logical conclusion. So perhaps DITA is doing the right thing by forcing their opinion of usability of user assistance systems by encouraging us to collect links in one location. My concerns after reading some usability studies on the topic are that perhaps 1) the placement of the related links could be improved and 2) as readers are trained by other information deliverables such as wikis and blogs that inline links can be clicked after reading the entire entry, DITA will be considered old school for its lack of inline links.

Perhaps we should change the DITA Open Toolkit transforms so that related links are in a on the side of the page instead of clumped together at the bottom of the page. I think that overall, DITA and topic-based writing has been a little unforgiving with the use of inline links. Since I can’t find usability studies that back up the claim that grouping related links together is better for users, and especially with sites like Wikipedia succeeding with inline links, I think that both types need to be given equal importance and flexibility for applying in the right way for the right audience and deliverable. What do you think?

I found the Tech Writer Blog directory from a post by Katriel Reichman who recently wrote me an email message in response to my post about Wikis for technical documentation – one writer’s story. Katriel has a nice post about rules for when a wiki would work well for tech docs. I’m looking forward to more posts with his insight on wikis and tech pubs.

He also wrote a post about the Tech Writer blog directory and the only rule about the blog directory is that no one talks about the blog directory. Wait, no, that’s not it. The rule is, if you add your blog to the directory, you mention the blog directory in your blog. Since it’s a wiki page you can edit the page to add your blog’s URL and feed.

I’m pretty excited about it also because it was my first chance to use my newly registered domain name, www.justwriteclick.com, which redirects to my blog here at talk.bmc.com/blogs/anne-gentle.

And the greatest feature of the Tech Writer blog directory (in addition to the fact that it’s a wiki page) is that they’re making an OPML file of the list as well as a Yahoo pipes feed. Neat!