Monthly Archives: June 2007

Yes I twitter.

I am enjoying twitter except for the fact that I think I’m quite bad at it. I’m annegentle on twitter if you want to add me and judge for yourself. Writing “tweets” with only 140 characters really makes me work hard. And then sometimes the end result makes me think the re-writing just isn’t worth it. Without editing, well, I just have to adjust to it.

Maybe my problem is that I always want to actually answer the question “What are you doing?” It’s right there above the post field and I want to answer it every time. But in reality, I think the more interesting tweets are clever, funny, entertaining, all in the span of 140 characters.

I haven’t mastered twittering but I intend to keep practicing. And reading all the good tweets I can get my hands on. Anyone have suggestions?

agile wiki

Wiki for tech pubs – ready for main dish status? Or still undercooked or side dish material?

Wiki Wiki Teriaki neon signWiki Wiki Teriaki neon sign, Austin, Texas

I’ve been doing some research for an article for the STC Intercom based on the interview I did with a friend of mine who does maintenance on the MOTO Q wiki. The article will come out this fall and I can’t wait to see if any rousing discussion appears on the STC forums. In the meantime, I want to continue to blog about wikis because I want to continue to research their use in the technical publications world.

I have had an interest in wikis for technical documentation for a couple of years now. There are a couple of good discussions on wikis for technical documentation from February 2007 on Tom Johnson’s I’d Rather Be Writing Blog as well as The Write Time blog. Tom’s post talks about using wikis to help with the documentation process. In response, there’s a wonderful entry by Lars Trieloff about exactly how a writer uses wikis for technical documentation.

While my STC Intercom article doesn’t talk about the internal wikis I’ve used for documentation tasks, as an Agile team member, I did find that the wiki housed information while development was ongoing and I also edited pages to keep them updated as I discovered something in the code that didn’t match the wiki.

It’s funny, in an early blog post I wrote on the internal blogs at BMC I said that I did not see how wikis would be used successfully for technical publications. I have since changed my once low opinion of wikis but I still see them supplementing other documentation, not substituting completely for technical documentation. I’d welcome discussion about wiki as standalone or supplemental end-user documentation. What do you think? Should the merits of wiki for certain products win out as the exact right documentation for that particular product especially one either related to an Agile methodology or social media? Or are wikis relegated to an upgrade to the customer support forum with a kludgey way of entering the information and no good method for outputting an information deliverable worth reading?

talk.bmc

Usability and technology for sewing, fabrics, and other domesticities

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.

When you don’t even know the answer to the secret questions

I signed up for a site called Aggreg8 that looks like it wants to be LinkedInfor IT professionals. Apparently it’s a Microsoft site with the tagline “The social network for IT Pros.”

To join the network, I signed up for my Windows Live ID. There is a nifty widget that indicates the strength of your password while you type it. It calls your password Weak if you only have a mixture of letters and numbers. Add in some mixed case and you move to Strong. I enjoyed this little widget immensely because of the immediate feedback.

Also on the same form, I was presented with a drop-down list of potential secret questions that I could answer when I need my password reset. Mother’s birthplace? Not sure if I know that. And do I typically answer City, State? Or City only? Grandfather’s occupation? Well in my case, both my paternal and maternal grandfathers had the same occupation, farmer, which is a likely answer for many people in my generation and the one generation above, perhaps. But with two potential answers I would have to guess at how I answered. At first glance I wasn’t sure which question I knew an answer that I would give every time I was asked. And on further inspection, I realized that I didn’t even know the answers to many of the questions. I also believe that some of these are the types of questions that a social engineer could extract from you pretty easily with casual light conversation.

So, kudos for the password strength checker, but I’m not convinced the questions with secret answers in order to reset your password are going to prove useful over time. I might be more protective of disclosing my grandfather’s career path in the future, too.

blogging

Welcome to the new Just write click blog

I haven’t decided whether it’s the just write click blog, or that I’m telling people to just write, click, blog. Blog as a noun or blog as a verb? Like Pimp My Ride, I’ll noun a verb and verb a noun.

Anyway, welcome! I am so excited about a hosted Word Press solution and thanks Cote for helping me decide that this solution is the best. You can always get here using www.justwriteclick.com, and the feed is always active. So please, just subscribe, read, and comment, to the new just write click blog.

DITA talk.bmc

A watched folder for publishing from DITA source files

I’ve figured out a way to automate DITA builds where you just drop a zip file of your DITA source files into a “watched folder” and PDF and CHM files are automatically built

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.

talk.bmc

Rob Houser’s review of the new RoboHelp, the first release by Adobe after they acquired Macromedia

I found this great review of RoboHelp by Rob Houser, who went to Miami of Ohio in the Master’s of Technical and Scientific Communication program two years ahead of me

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.

talk.bmc

Word visualizations are very useful

I received a pointer to the Visual Thesaurus in response to my web visualizations post and I had to blog about it.

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.

talk.bmc

Watching web goings-on live with visualizations

Watching activities live on the internet, especially in the Web 2.0 space, offers endless entertainment.

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?

talk.bmc

Using the del.icio.us bookmarklet button

With del.icio.us, you can collect your favorites or bookmarks on the web, tag them with keywords, and then access them from any computer. I have stopped using all other bookmarker tools and have imported all my favorites into del.icio.us.

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.