RE: Task-based versus UI-based documentation

Subject: RE: Task-based versus UI-based documentation
From: "Lippincott, Richard" <RLippincott -at- as-e -dot- com>
To: John G <john -at- garisons -dot- com>
Date: Thu, 7 Aug 2014 17:05:11 +0000

John G. said:
> It's all about the mental gymnastics required to assimilate the complex vagaries of a software system vs. the physical ability to touch, feel, plug in, and use a hardware component.

But you don't always have the opportunity to handle the hardware. I've never actually -flown- either the C-5 or the F-117 aircraft (no matter how much I begged and pleaded). (If I had, you know I'd have bored you with the stories long ago.)

My counter to what you're saying is that currently my co-worker is documenting the hardware of a new X-ray system that hasn't been built yet. Our primary resource is the SolidWorks model. Ironically for this discussion, when the system is built and he runs it, he will be using the UI. The only hardware he's ever going to touch will be the mouse and keyboard. Similarly, about a year ago I had to create an operation and service manual for a new scanner that, likewise, hadn't been built yet. The only hardware I got to touch was the laptop that ran the UI simulator.

I've created aircraft structural repair manuals by using only the blueprints, because the first airplane hadn't been built yet. I worked with a guy who had to come up with a complete manual for stripping the hydraulics and electrical systems out of a 2,000 pound aircraft ski when the airplanes were all down in the Antarctic.

I've been in the position where the hardware existed, I could see it, but company rules prohibited me from actually touching it. (In some occasions "This is the only one, and it's complete, so you can't take it apart." In others "Company rules prohibit someone in your job classification from actually touching the hardware.")

Then there's stuff that touching and feeling doesn't even begin to help with. What's the impact on fatigue limits when the material changes from 7475-T6 aluminum to 7079-T6? Or the impact on crack limits in a jet engine turbine blade when the alloy is changed? Guess wrong one way, the customer needlessly scraps very expensive parts. Guess wrong the other way, lose an airframe and crew.

What happens when for some bizarre reason the company decides that event though the product is built in Groton CT, the tech writers are going to be based in Atlanta GA? This was the case with nuclear submarine manufacturer General Dynamics during the 1980s...and no, the writers weren't allowed to keep a sub in the Chattahoochee River. (Why did GD do this? Because the pay rate for tech writers at the time was significantly lower in Atlanta than it was in Groton.)

Maybe it's just my opinions are colored by the type of hardware I've been documenting over the years. "Hardware" does cover a very wide range of systems, after all.



Rick Lippincott, Technical Writer
American Science and Engineering, Inc. | www.as-e.com Â
Office +1-978-262-8807 | Fax +1-978-262-8702
rlippincott -at- as-e -dot- com
Follow us on Twitter @ase_detects









From: vwritert -at- gmail -dot- com [mailto:vwritert -at- gmail -dot- com] On Behalf Of John G
Sent: Thursday, August 07, 2014 11:30 AM
To: Lippincott, Richard
Cc: Julie Stickler; Cardimon, Craig; TechWR-L
Subject: Re: Task-based versus UI-based documentation

It's all about the mental gymnastics required to assimilate the complex vagaries of a software system vs. the physical ability to touch, feel, plug in, and use a hardware component.
In software you have to do more ground preparation for users as a lot of what needs explaining requires the user to "get" some concept or behavior. I have found that's less onerous when documenting hardware.
Software, IMHO, does not really "exist". Sure, it's positive and negative 0s and 1s on a whirling disk, but that's not really existence. What it is is a series of rules and behaviors - click this or enter that and something somewhere else changes as a result (and frequently changes in a way that it not immediately apparent). That's different than physically pushing or connecting this and you see/feel this happen.
But hey - I was a philosophy major, and I have to say I'm using the same skills I learned when analyzing Kant's Phenomonology so that I can justify it all ...
My 2Â,
JG

On Thu, Aug 7, 2014 at 11:16 AM, Lippincott, Richard <RLippincott -at- as-e -dot- com> wrote:

Hardware writing is pretty much like writing about software, just that it hurts more when you drop the actual product on your foot.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
Task-based versus UI-based documentation: From: Cardimon, Craig
Re: Task-based versus UI-based documentation: From: Julie Stickler
RE: Task-based versus UI-based documentation: From: Lippincott, Richard
Re: Task-based versus UI-based documentation: From: John G

Previous by Author: RE: Task-based versus UI-based documentation
Next by Author: Software documentation that uses effective visual metaphors?
Previous by Thread: Re: Task-based versus UI-based documentation
Next by Thread: Re: Task-based versus UI-based documentation


What this post helpful? Share it with friends and colleagues:


Sponsored Ads