TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
RE: How is documenting hardware different from documenting software?; was, "Re: Is there a study on reading warnings, notes?"
Subject:RE: How is documenting hardware different from documenting software?; was, "Re: Is there a study on reading warnings, notes?" From:"Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com> To:<klhra -at- yahoo -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 6 Nov 2008 11:19:16 -0800
Do you prefer one to the other? If so, why?
Thanks!
Leonard
-----Original Message-----
From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of Keith Hood
Sent: Thursday, November 06, 2008 11:09 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: How is documenting hardware different from documenting
software?;was, "Re: Is there a study on reading warnings, notes?"
You have to start by defining what the customer means by "hardware."
Does he mean the business end of a CNC machine or the workings inside a
CPU chip like the north and south bridges?
If you are dealing with large-scale hardware, you will need to pay very
close attention to physical safety concerns for the user. Depending on
the kind of hardware, your warning notice hierarchy may need to include
the possibility of the user being injured or killed if he does something
wrong. That concern must also be reflected in any user-level procedures
you write, so you tell him how to remain safe by telling him what NOT to
do.
If the hardware is things at or near chip level, you'll probably have to
work a lot on documenting signal flows and timing diagrams. If you're
working with circuitry, brush up on your Boolean algebra. That will make
it easier to understand designs, and help you notice if something seems
to be wrong.
It seems to me that in a hardware environment, the review process is
stricter. Programmers and those who manage them seem to be less inclined
to take time away from their "real" work to review docs. They always
want more leeway in which to exercise their version of creativity, so
they are more likely to not care about "slop" in documentation. In a
production environment there is more emphasis on metrics and adhering to
production plans, and both the deadlines and the standards for docs are
tighter. In the last 10 years, I've worked at a couple of hardware
producing companies and they both had documentation management
structures that included editors and proofreaders, but none of the
software companies had anything like that. It may have been a function
of the fact the software companies were much smaller.
--- On Thu, 11/6/08, Leonard C. Porrello
<Leonard -dot- Porrello -at- SoleraTec -dot- com> wrote:
> From: Leonard C. Porrello <Leonard -dot- Porrello -at- SoleraTec -dot- com>
> Subject: How is documenting hardware different from documenting
software?; was, "Re: Is there a study on reading warnings, notes?"
> To: "Gene Kim-Eng" <techwr -at- genek -dot- com>, techwr-l -at- lists -dot- techwr-l -dot- com
> Date: Thursday, November 6, 2008, 1:56 PM
> I've documented some hardware, but for the most part, I
> have worked in
> software. I sometimes think about moving into
> hardware/machinery
> documentation, and Gene's comments got me to wondering
> what the
> difference is between documenting software versus
> hardware/machinery.
>
> Is the process much different?
> Is the lifecycle of one generally longer or shorter than
> the other?
> Does one generally entail better review processes than the
> other?
> Is one generally more fun than the other?
> Anything else?
>
> Obviously, some answers will depend on personal
> disposition, but I'd
> still like to hear what people have experienced.
>
> Thanks in advance.
>
> Leonard
>
>
> -----Original Message-----
> From:
> techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
>
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
> om] On Behalf Of Gene Kim-Eng
> Sent: Thursday, November 06, 2008 10:42 AM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Is there a study on reading warnings, notes?
>
> A partial list of my past products, both as an engineer and
> a writer (I think I've mentioned some of these
> previously):
>
> Helicopter rescue hoists
> Handling and loading equipment for ICBMs
> Semiconductor fabrication equipment (lethal chemicals,
> megavoltages,
> lasers)
> Mass spectrometer and chromatography instruments (more
> lasers)
> DNA sequencers (still more lasers)
> Architectural/industrial scanning equipment (surprise!
> lasers again)
> Aircraft power management systems
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> ComponentOne Doc-To-Help 2009 is your all-in-one authoring
> and publishing
> solution. Author in Doc-To-Help's XML-based editor,
> Microsoft Word or
> HTML and publish to the Web, Help systems or printed
> manuals.
>http://www.doctohelp.com
>
> Help & Manual 5: The complete help authoring tool for
> individual
> authors and teams. Professional power, intuitive interface.
> Write
> once, publish to 8 formats. Multi-user authoring and
> version control! http://www.helpandmanual.com/
>
> ---
> You are currently subscribed to TECHWR-L as
> klhra -at- yahoo -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit
>http://lists.techwr-l.com/mailman/options/techwr-l/klhra%40yahoo.com
>
>
> To subscribe, send a blank email to
> techwr-l-join -at- lists -dot- techwr-l -dot- com
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwr-l.com/ for more resources and info.
>
> Please move off-topic discussions to the Chat list, at:
>http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and
publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as
Leonard -dot- Porrello -at- soleratec -dot- com -dot-
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
