Monthly Archives: September 2007

techpubs tools

Adobe’s Technical Communication Suite announced

Adobe has announced a Technical Communication Suite, combining FrameMaker, RoboHelp, Captivate, Acrobat 3D, and Flash, available in October 2007 for $1599 or $999 upgrade pricing if you already own one of the tools. This price point is well below what buying those products individually would cost (compare to $3600). I’m about a day late to the flurry of blog posts, as there are many bloggers commenting on this release, but many of them are focusing on the FrameMaker to RoboHelp single sourcing aspect, including the Adobe Technical Communication blog.

Scott Abel, The Content Wrangler, noted the price temptations, especially for people currently on RoboHelp. I’d just add that the upgrade price is the same price as Adobe Creative Suite 3 Web Standard ($999).
Dan Ortega’s message from Astoria appears to be but there’s no enterprise workflow and it’s a desktop solution, meaning, tech writers will still be the only users in a company using FrameMaker. Charles Jeter notes the same lack of collaboration in the suite in a nice wrap up post as well.

Sarah O’Keefe notes that most of her clients are going lighterweight than FrameMaker for their XML solutions.

Bill Swallow (techcommdood) notices that you can only go from Frame to RoboHelp, not back.

While single sourcing is always interesting to me, what I’m curious about are the use cases for Captivate, Acrobat 3D, and Flash, when using this Suite. I’ve used FrameMaker and RoboHelp in the past, but haven’t gone beyond the trial version of Captivate. So I looked at the webinar listing and there are hints at use cases that are an interesting sweet spot for the technical writer who wants to move past the static manual into interactive user assistance – not to mention the technical trainers looking for the correct tool to build interactive demos. Here are some catch phrases I lifted that might be just marketing-speak, but also might speak to where our profession is headed.

  • track help system usage
  • leverage existing content to create interactive help or performance support
  • question randomization
  • animation imports from PowerPoint
  • do this cool buzzword stuff… without the help of your engineering department

So perhaps a key aspect of what Adobe has heard from tech writers all over is, we want to do cool stuff, but we’re not getting the resources we need to program the cool stuff.

And indeed, the webinar folks seem to want to help define where we’re headed and how we’ll get there. To quote from the intro paragraph, “What does this mean for technical communicators, instructional designers and eLearning professional today and tomorrow?” As go the toolset, so goes the career? I suppose that the skill demand certainly shapes what you learn as a technical communicator in order to stay employable. Does your software toolset make you do your job a certain way?

techpubs tools

Author IT – boldly climbing the learning curve

I thought I’d continue posting about my experience with Author IT since my initial review of AuthorIT. This past month I’ve been exploring ways to help out with the Author IT nuts and bolts, doing maintenance-type and infrastructure tasks such as changing the on-screen style formatting and revising a book template.

I’ve also been learning more about what is involved with the overall tasks of maintaining single source with nearly 20,000 objects in your library. Objects can be topics or books or hyperlinks or index entries or graphics or… many other items, so I’ll have to dig deeper to get a sense of how many topic objects we deal with daily. Ah, here we go – do an Advanced unqualified search filtered for results Of type “Topic Object” and then select the ones not marked “Obsolete” or “Orphaned” (meaning not used in a book object) and the answer is, we have over 7,000 topic objects in our library.

I maintain that the learning curve is steep but I’m fortunate (or sometimes unfortunate) that I’m approaching these tasks with an idea of how I think it might work. Plus I have an Author IT expert sitting in the office next to me who still answers my IMs when I ask Author IT questions. (Thanks, Mary!)

Changing the state

It is still taking me a while to get accustomed to the workflow that requires that I change the state of an object before making edits to it. If the topic I want to edit isn’t in a writeable state, then I can’t make my edits until I locate the object so I can right-click it to change the state. Maybe I’m missing some shortcut to how to change the state while editing a topic’s text. I’ll have to poke around the tabs a while. It’s more likely that I need to make a shift in my workflow and remember to select the topic objects I want to edit, change the state, and then begin the edits.

Search mechanisms

My understanding is that there are two basic search mechanisms and both are rather underpowered for the amount of legacy information we have stored. (I’ll have to get a topic count to give real numbers here.) The first search mechanism is searching the entire collection of topics and books and sub books. The Advanced Search checkbox is always checked in my environment.

The second search mechanism is on the actual text within topics – you can search for text within a topic, within a book, or within the entire library. This mechanism is found from the Edit > Find menu command in AuthorIT Enterprise Edition.

What I’ve found recently, however, is that you cannot replace formatting on the found items. This limitation means that you could have semantically tagged items that are not able to be retagged. For example, if you had tagged all your menu items as “menucascade” but needed to change the tagging to “breadcrumbnav” you would have to export the topics to an XML editor and do search and replace there. I don’t yet know how to batch export say thousands of topics to do this search and replace to get the semantic tagging you wanted. This analysis and potential workaround is based on searching within the Author-it Yahoo Group’s messages, so perhaps there is another way to search for text and formatting and change both the text and the formatting but I haven’t found it yet.

Even with these two search mechanisms at our disposal, we find it easier to use a Google search tool on our external database at docs.imis.com, then right-click on the HTML page to get the topic ID, then use that topic ID to search the AIT object database.

Author IT Yahoo Group

Now, I just went through the Yahoo Group messages again to learn more about the searches in AIT, and I really do like the community there. People are very helpful and still maintain a nice sense of humor and goodwill. That’s an important aspect of any tool selection I think. Anyway, there is a way to search within a set of found items, and that is to do a Search using the Search tab first, then press Ctrl+A to select all topics found that match the search criteria, and then do the Find and Replace command on the selected topics. That search also revealed a potential limitation of AIT’s inability to find period space space and replace it with period space (explanation of why period space is correct, because The PC Is Not A Typewriter).

A third search mechanism that we could make use of but that doesn’t yet exist would be the ability to search within a folder. We can use the trick mentioned above where you select all the objects in a folder then do a Find. A Folder in AIT is just a representation of the objects in a collection within a folder in the CMS of AIT (sorry, too many acronyms to qualify as a real explanation, but it’s basically another view of the database but not searchable within each Folder). But that’s a find on text, not a find on objects or metadata on those objects.

Variables to substitute text values

I find that the variable mechanism is a little bit clumsy. Variables are simply text enclosed in angle brackets <substitutethisforthat>. So you still have to do a search and replace for text when you want to choose a different variable name. If you use angle brackets in your documentation, AIT has to be told specially that you meant to do that and that those should not be resolved to a variable name. So, if you really want angle brackets to appear as angle brackets and not resolve to a variable, you have to use the HTML trick of ampersand lt semicolon.

Running AIT publishing from the command line

One nice feature is the publishing engine’s batch processing that will even output the commands for you so that you can include it in a batch process. We found that the outputs are always placed within the users folder that is logged in to AIT, despite using a documented command line parameter where you feed in a user and password for running the batch processing. Mary found a nice workaround where she just copies the files she needs out of another folder (the _Output folder in our environment), but it seems like a waste of disk space to me to have a second copy of output in each user’s folder. We can do some cleanup using the batch files to ensure that disk space is freed up, however.

Magical price point

Let’s face it, since it’s in the four figures for a seat license, Author IT is a relatively inexpensive all-in-one single sourcing tool that has both a straightforward editor and a content management system. A small techpubs department looks pretty darn good when they can deliver manuals and help as part of an automated build in a lights-off no-touch system. And the savings in translation costs when you single source are unmatched.

Where AIT “feels” inexpensive though, is in the slightly outdated interface (why can’t it remember the window size after being shut down?), somewhat underpowered search methods, and so far, I just can’t shake the general feeling that you’re not really owning or editing “source” files but rather some Word-like representation of the source.

Still, it works wonders and lets our small techpubs department output some high-quality professional content, more content than possible without a single-sourcing tool. So I’ll face the learning curve and continue to climb it.

tools

For those of you who want your computer to just write what you say

I’ve been keeping an eye on the search keyword list for this blog. The hits are typically from search phrases like “technical writing” “masters degree” and “agile documentation.”

But one phrase that I found interesting was “just write what I say.” I would guess that the person is seeking voice recognition or speech recognition software, specifically verbal transcription tools. I suppose Dragon NaturallySpeaking is the first product that comes to mind, but there are OS-based options as well. I like their product’s tagline, “Turn talk… into text!” so props to them and a link.

Speech recognition can be integrated into certain programs on Windows XP SP1, such as Microsoft Word and Notepad, as this article from September 2003 describes, but you need Microsoft Speech Recognition Engine v5.0 and naturally, a microphone and hardware that can take in the speech sounds.

Mac OS X has speech recognition integrated as well, and you can even play chess with the computer giving it voice commands, according to this web page.

So, I’m writing this post to gather some traffic but offer useful information while collecting those hits. Give back, I say. Let me know if you found this information useful.

The anti-social folksonomist

I’m finding that in del.icio.us I’m using keywords that no one else uses. Does this mean I’m an anti-social folksonomist?

This discovery reminds me that it’s important for findability to have tags that others will use too. On sites where popularity counts, it might be better to match others’ tags depending on what your end goal is – is your goal to categorize for your own easy retrieval later, or to tag so that others can see what you’ve tagged as being similar to their own findings?

For example, I use a tag called “blogthis” for items that have caught and held my interest but I don’t have time to immediately write a blog post about the item. Apparently no one else uses this tag! Or if they are using a “blogthis” tag, it’s those items aren’t shared.

Tagging is so easy, especially the way it’s implemented on sites like flickr and del.icio.us. But what conscious decisions are you making when you select a tag? This article has a good cognitive analysis of the act of tagging. To me, the lovely and freeing part about folksonomies for taxonomy is the decoupling of concerns about “matching” others tags and the ability to have multiple categories with similar meanings.

What does easy tagging mean for indexing professionals? Is it the crowdsourcing of indexing? Or is the printed book still a strong enough meme that a professional index is a requirement for certain media? Or is it a third, hybrid being, with identity and authority tied up in the tag selection?

tools

Hyperviews Online article about CMS for website

Here’s a link to my latest article on Hyperviews Online, the newsletter/blog for the Society for Technical Communication Online Special Interest Group (STC Online SIG). It’s called Using a Content Management System (CMS) for your STC community web site.

The STC Austin chapter is re-designing the community website, and I volunteered to help. We started researching CMS use and I found that quite a few sites were using WordPress, so I emailed the webmasters to learn more. The article is a result of that email survey where I learned more about WordPress as a CMS.

techpubs writing

User and task analysis – or, how do I start writing anyway

My writing teammates and I are working through our favorite ways to start a project and do user and task analysis. The exercise forced me to write down what it is I do when starting a new project.

My formal training began in graduate school but my practical training happened at only two different companies, Rockwell Software and BMC Software.

But the basic principles I follow are: do task analysis by reading everything available about the feature, reading about the typical users (personas are great for this goal), searching the internet for examples of the features in use, and then interviewing people to fill the gaps in the information available to me.

Next, I start by outlining what topics should be written and if there is a set of templates available I will always use those to the fullest. I guess that my outline-first approach is why the TOC standards are important to me. If I’m editing existing content I keep the users’ goals in mind while editing.

I have used the Hackos and Redish book User and Task Analysis for Interface Design and I like it. Also, I have A practical guide to usability testing by Dumas and Redish on my bookshelf.

Usability is so integral to task analysis, which is why much on the web is usability-based rather than writing-based I believe.

Basic task analysis: http://www.usabilitynet.org/tools/taskanalysis.htm

Task analysis grid using an Excel spreadsheet: (Fixed link using archive.org).

I’m using this spreadsheet only slightly modified to analyze user tasks for setting up a certification program and it has been so helpful so far.

Six Steps to Better Interviews and Simplified Task Analysis:
http://www.adaptivepath.com/publications/essays/archives/000295.php

I’m sure that this post doesn’t capture all of the things I do when approaching a writing assignment but it helps to write it down and analyze my methods to look for improvement.

Use a blog to respond to a blog post?

I’ve been diving deeper into social media and its use to make connections via email and also in real life. For example, I had a great lunch conversation with Alan Porter at Quadralay a few weeks back. We made the connection thanks to a comment conversation on Tom Johnson’s blog, I’d rather be writing. I had asked Alan how Quadralay responded to some constructive criticism about their product wiki, and he said he talked to the blogger at the next conference they both attended and had a really nice conversation, clearing up the confusion. That interpersonal approach works well because it forges the relationship rather than simply connecting blog posts. It’s using social media to make that next connection meaningful.

My next question was, why don’t you have a corporate blog where you could respond to the blogger via comment on the very blog post that could be interpreted as critical, therefore using the blog medium that the blogger was using? Then, when my search about WebWorks wiki came across this post, I could have had Quadralay’s response to read along with the post.

My theory is that the Adobe Technical Communication blog has been set up for this very purpose. In my opinion it’s an effective Public Relations move, because you are creating the record that you want to be available for years to come when the search term is found again. But I’m sure Adobe’s team has to prove that the time spent blogging and the money spent on the blog infrastructure and tools was money well spent.

Effectively, any blogger must prove that there would eventually be a return on that investment of time and money. I think that the return could occur months or years later when someone like me is researching their next toolset. It’s the influence that the bloggers can wield, which then translates to investment, which I discussed in my prevous post about the Reach and Influence of blogging.

Currently, I get paid with a pseudo-currency of community connections more than any actual currency payoff with my blog, and I like it that way. My blog is driving the boringness out.

techpubs wiki

Emerging wiki use – now and future wikis

As you might have seen on The Content Wrangler recently, I wrote a response to JoAnn Hackos’ article, Is there a wiki in your future? and Scott Abel chose the title for my special contribution to his site. I think the title of this blog post – Emerging wiki use – now and future wikis – would have been a better title than “Anne Gentle vs JoAnn Hackos” but unfortunately I learned that his blogging system would cause broken links if he changed the title after I requested a title change. Ah, content management systems, why do they break your heart? :)

I do want to make sure that readers know that JoAnn and I are not at odds about wiki use at all – rather, we are both trying to find the best practices for building a wiki that will thrive. My thought on the “vs” in the title is that it is intended to show the polarization on the issues surrounding wikis and technical publications. JoAnn and I have emailed back and forth this week to continue to discuss and find that we are not on opposite sides of the issue.

I’ve happily read the blog entries from other writers that read both articles, with my favorite reference being Sarah O’Keefe’s “eponymous rebuttal” phrase. Subtle and clever, and sent me to m-w.com, so I love it.

A neat outcome so far from this article is that I had a discussion with someone who had experienced something similar to JoAnn’s scenario. One of my readers described a situation where he was creating and updating wiki pages, trying to extract and describe an exact algorithm for an online game. Apparently in gaming communities, the developers can be very tight-lipped about the exact way that game play works (weaponry or armor for example), and the challenge to the gamers is to figure out the best strategies based on their experiences with the game. Without arbitration on the wiki (or customer support forum), though, outright content wars ensue and the wiki content about the algorithm becomes untrustworthy.

It’s a fascinating example. I’d like to find more examples related to technical content to find out what arbitration policies would work well. Let me know your experiences in this area – have you had a need for arbitration on your favorite wiki yet?

nptech

Non-profit technology mashup with LOLcats

I found this image on the new lolnptech site, and the site gave me a good chuckle. The cat is saying “Oh noes! Manual waz written 4 geekz not social workerz!”

This particular image hit home since I help write the manuals for iMIS. Typically our audience isn’t doing social work, necessarily, though. More likely we are writing for associations, professional organizations, or church offices where data entry for contacts and events is high on their list of to-dos.

OH NOES! MANUAL WAZ WRITTEN 4 GEEKZ NOT SOCIAL WORKERZ!

In case you haven’t be exposed to such an image before, it is a new trend or Internet fad that even Time magazine has covered in the recent article, Creating a Cute Cat Frenzy. The images are often called cat macros or LOLcats, and I Can Has Cheeseburger is the original collecting site for such images. Apparently cats can’t do subject-verb agreement, cats like to use texting shortcuts, and prefer to use l33t 5p34k (elite speak).

Keep up the good work, kittiez.