Monthly Archives: January 2009

work

Arrrrrrr, mateys!

I haven’t been churning out blog posts for a while due to a crazy birthday party incident. I don’t usually tell personal stories on my blog, but I thought I’d personalize this tale and talk about how grateful I am for how it is turning out!

The order of events went something like this:

Party

Saturday early evening. Arrived at large jumping inflatables party place for a five-year-old’s birthday party. Remarked offhandedly to my husband, “I always get pinkeye after going to these types of places.” Boy was that a premonition.

Got a front-row seat to the beating up of a large Darth Vader piñata with a wooden stick.

On the very last blow, just when the payload fell out of Darth Vader, the piñata bat slipped out the 10-year-old’s hands and hit me in the eye and my son, who was sitting in my lap, in the stomach. Ouch hardly begins to describe the incident!

Ouch

Organized chaos ensued and somehow I managed to bleed on other moms, not on myself. My kids were shook up but fine, the party-goers were ushered to a party room for pizza, and we made arrangements for our children, started icing the cut below my eye, and my husband and I took a trip to the nearest hospital.

Hospital Trips

After it was apparent that no eye doctor was answering to their informal on-call arrangement, I was transported to a teaching hospital about an hour away by ambulance. My husband went home to get our kids to bed, another mom slept on our couch to stay with our kids, and my husband drove to the second hospital an hour away.

The continued evaluations and a CT scan revealed that I had an orbital blowout fracture, a hyphema, a cut requiring two stitches in my upper eyelid, and a cut below my eye that was glued back together. All this from a wooden dowel rod flung about 20 feet!

Recovery

But I’m feeling much better this week and I am so grateful to get my eyesight back that I really don’t care about potential scarring or pirate eye patches. My energy level is still pretty low, which I’m not accustomed to at all. I need to sleep eight hours? What?

img_3666

Apparently I will slowly regain all my eyesight as the blood in my eye gets filtered out. Day by day it improves and I’m amazed at the way the body heals itself. I’m down from three sets of eyedrops and an eye ointment to one drop at night and a clear plastic eye patch while sleeping to ensure I do not accidentally rub my eye.

Three different emergency department personnel asked if the event was captured on video! I’m pretty sure no one was rolling film or tape, thank goodness.

I got a great pan of brownies and a wonderful hand-made pop-up Get Well card from the stick swinger. He’s recovering from the incident as well and we’re all going to be just fine. Darth Vader is a crumpled mess of cardboard, as it should be. That guy really is evil.

Gratitude and Admiration

I’ve known people in the software industry who work with serious eye issues, and I have an even greater first-hand admiration for their tenacity to stick with such a visual profession.

I do try to learn as much as I can about web accessibility. I’ve participated in AIR Austin‘s accessible web design competitions, judged by Section 508 Guidelines for Web Accessibility. It was quite revealing when we were told to turn off our monitors and try to reserve plane tickets!

Yet I know I can learn more and do more. Keith Soltys has a great blog entry, In the country of the blind, where he talks about not being sighted enough to drive, and gives a great example of blind Google engineer making a difference to others dealing with vision issues. I’m here as a reminder that it can happen to anyone.

Embrace the “un”

Embrace the un article thumbnailAn article that Janet Swisher and I wrote for STC Intercom magazine about unconferences, BarCamps, and Book Sprints is available as a PDF file from the stc.org site if you are an STC member. I have permission to post it as well, so click the image for a free download of the PDF file.

Janet and I collaborated on the article by using Google Docs and sharing the editing between us.

Here is an excerpt:

Embracing the Un — When the Community Runs the Event

While Web 2.0 has many definitions, it is fair to say that Web 2.0 involves embracing user-created content and the communities that emerge around that content. One aspect of being a member of a Web 2.0-enabled online community is the real world meetings that can happen at professional conferences or even networking events in your same town or city. User groups or focus groups are one type of real-world meeting, with a single goal in mind.

Unconferences and barcamps are another type of real-world event where people with similar interests and goals can get together to share information. A third type of community event has just emerged and this article highlights aspects this new BookSprint model because of its relevance to technical writing. This article describes the authors’ experiences with participating in these types of events, and in particular the FLOSS Manuals Book Sprint for the One Laptop Per Child (OLPC) project, held in August 2008.

Read more

techpubs tools

Author-it Table Of Contents expansion

My co-worker Melissa Burpo (yep, I interviewed her before she was my co-worker) has solved a nagging problem with the HTML output from Author-it. The Table of Contents would always lose your place when you expanded one of the TOC items – instead of “keeping your place” vertically, it scrolls your view to the top of the frame. We have a long table of contents and this particular implementation got a lot of complaints.

Rather than shorten our Table of Contents (I would guess that’s what most shops have done), Melissa used Javascript to capture the scroll location, save the location using a cookie, and then reload the scroll location after you expand or contract the Table of Contents.

She’s allowing me to publish her solution here – let us know if you find it useful! You can see it in action at docs.imis.com.

Inserting code into your Author-it Table of Contents

Download the toc_scroll.js file supplied here and save it to your HTML Templates directory, such as C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML\.

Open the toc_template.htm file supplied with your Author-it installation in C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML\.

In the <head> area, insert a pointer to the toc_scroll.js file using this code:
scriptcall
In the next few lines of the toc_template.htm file, give the starting point for the scrolling to load.

functioncall

Modify your book so that it includes the new toc_scroll.js file and the new toc_template.htm file.

Publish your book using these modifications.

We’ve tried it on Windows XP and Vista, IE 7 and 6 and Firefox 2 and 3. Let us know your thoughts on this “fix” for a scrolling annoyance, and if you use it, give a hollah!

techpubs

How many roles can a documentation expert have in a company?

Harjot Dhodi asked, “What is the difference in the role of: Document Architect, Template Designer, Writer, Technical Editor, and Production Editor? Can a person be told to handle all these roles?” I’ll try to examine these roles one at a time, and then answer the final question last.

Document Architect – Typically this person has a “big picture” view of the documentation and how to organize it to fit the user’s needs. This role involves organizing, dictating what topics will be written, structuring the overall deliverables (especially if there are multiple deliverables such as online help and printed documentation). I would say this role is for a more experienced person who has been with the company a while and knows the business needs for the documentation.

Template Designer – This person knows the documentation tools well enough so that they can maintain and design templates used over and over for consistent documentation while authoring so that the out put look and feel is the same over and over. For example, the role would involve designing FrameMaker templates for books and chapters and styles for the authors to use while writing.

Writer - This person creates the content. They should be familiar with using the templates and the style guide for the company.

Technical Editor – This person reviews the content and may also maintain the style guide. Some times the term “technical” in an editor role means they will check the documents for consistency with the product and technical accuracy throughout the document. Grammar and style rules checking is also part of the responsibilities of this role.

Production Editor – This phrase is less familiar to me. I would imagine that this person reviews output for any errors and does link checking for online deliverables. I suppose it really depends on what deliverables are produced. The Production Editor may need to check CDs to ensure the documentation deliverable operates correctly on the CD. There could be a lot of editing and testing and checking on certain production deliverables.

Can a person be told to handle all these roles ?

I think one experienced person could handle all these roles, and a single person could learn one role at a time and just keep adding each role to their abilities. In my company we do not have separate editors so we must review each other’s content. We all write content, we all edit content, and we have a document architect and production editor who is most familiar with the content and production tool.

Does this help answer questions about documentation roles? I’d love to hear feedback from my blog readers as well – what have I missed or what additional roles might there be placed upon one person?

techpubs tools

Adobe AIR for an interactive children’s story book

Storybook Anytime is a Flash and Adobe AIR website for kids to have their own stories in a library. It’s a great example of Adobe AIR, a technology I’m curious about for online help use. Here’s a few screenshots of the website:

My library

Kid mode

Plus, the entire library is free to pre-schools, grade schools, and public libraries. I’ll have to investigate this for our preschool. We recently installed new Dell computers for the staff and teachers and for classrooms for kids age three and up. That project took up a lot of my blogging time over the holidays but it was well worth it!