Re: How is documenting hardware different from documenting software?; was, "Re: Is there a study on reading warnings, notes?"

[Keith Hood <klhra -at- yahoo -dot- com>]

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 archive -at- web -dot- techwr-l -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/archive%40web.techwr-l.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