Thursday, April 26, 2007

Creating an Image Report with RoboHelp

When I discovered that my primary layot is On-Line Help, and therefore switched from writing with MS-Word to writing with RoboHelp, I have started to hide my screenshots.
Instead of presenting the reader a set of steps that span through several pages, I deliver a 10-rows-long text-only set of steps whose screenshots are hidden behind the text. Clicking a step reveals the screenshots and most of the readers are usually happy with that.
The problem within this arrangement is the way I maintain these screenshots. Ever so often I am required to update the On-Line Help to match the product's new GUI. In some of these cases, only the GUI changes, while the logic (the way the user uses the application) remains intact. Such a screenshot replacement should be a breeze. It is, indeed, very easy, given that I know where my screenshots are.
How do I know that?
Writing into MS-Word, I simply run through the pages, look at the shots and replace them on the spot. RoboHelp is less intuitive here (no such thing as run through the pages...) but it provides an Image Report.
Quickly bypassing the report's pitfalls (Selecting All Folders doesn’t recognize Conditional Build Tags; Selecting a parent folder results in an empty report) we come up with a list of all images per topic. Properly laying out the topics (i.e. one task sequence per topic), the images read task1-image1.gif, task1-image2.gif, etc.
(Blogger allows for a single picture per post, so no more images for you. Come back other day.)
Earlier this week I have copied such a report into an MS-Word file, along with tiny-little-hand-crafted screenshots icons. Too much work.
Generating the report on a daily basis throughout the project, should do.

Wednesday, April 18, 2007

Flatland - the metaphor works in both directions

BlogScholar (to whom I have arrived via Commitment to Living) writes that academics should leverage themselves through the blogosphere.
I am not going to add my two cents to the "of course you should have a blog or two, too". Instead, I would like to state that one of reasons I'll probably won't see the university from within is that all I need to know is available on-line.
Sure, there are lots of things I would like to learn. Moreover, there are plenty of things I need to learn (for example, in order to stay in the business).
However, instead of driving to the nearby university campus, guessing whether I have chosen the right professor for my needs, guessing I know what my academic needs are, and keeping them from evolving throughout a 13-weeks long semester, *
instead of doing all that, I am quick-searching a subject, read a post or two (or two-dozens, depends on how long does it take me to get it straight), post several comments with questions, and always get a decent feedback from the blogger.
The land is, indeed, not flat anymore, and it works for non-academics as well.

* OK, no English professor would ever allow me to write such a long sentence. Maybe the university has a point after all ;-)

Monday, April 16, 2007

Selecting an authoring tool

The technical writer's wet dream looks like this:
"I've recently joined a startup company that has never had a techwriter and needs me to write all the doc from scratch."
Being a wet dream, this question has more that one right answer. However, as I managed not to send my reply to the group (one of the strongest YahooGroups features), I recall it here.
I'd go for constructing a writing culture from scratch. Having my documents reviewed by Markeing / PM / R&D is crucial for their quality. Writing in FrameMaker, PDFing the document and shipping it to R&D for a review, is actually saying "Please don't comment to this document. If you feel you must comment to it, a 'job well done' will do. Here, let me spell 'job well done' for you".
Writing in MS-Word, on the other hand, is far better. Tech Writers don't like Word for several good reasons. However, Word allows for tracking changes in a manner no other writing tool does. Having the document straight with all R&D comments taken care of is far more important than having an FM file nicley * transferred to WWP. **
Tech Writing is a customer facing business. Keeping that in mind makes happy customers. Happy customers make rich Writers.

* I know that 'nicely' is very generous here
** If you don't know what WWP is, count yor blessings