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:"CL T" <straylightsghost -at- gmail -dot- com> To:"techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 6 Nov 2008 12:33:50 -0700
I've done a fair amount of both. In short I prefer documenting software.
Is the process much different? I have PMs assign SMEs and gather information
much the same way. Documentation is usually a little different (a lot more
photographs and graphics). I also write for multiple audiences in one
product. Some/parts of the documentation are aimed at techs while other docs
are aimed at consumers (a Quick Start Guide, for instance).
Is the lifecycle of one generally longer or shorter than the other? In my
industry, the lifecycle for hardware is Much longer. I do see a lot of
updates, tech notes, release notes, etc. coming across that aren't added to
the manuals.
Does one generally entail better review processes than the other? Heheh,
that's almost always the breakdown. Review is a dance between "Not technical
enough" or "It's too technical for consumers". I've begun implementing
Sign-off Meetings.
Is one generally more fun than the other? My opininon? I like documenting
software more than hardware.
Anything else? Development cycle and processes are MUCH longer for hardware.
Localization is a fact of life (which creates its own problems when/if new
translations aren't included in the budget!) And RoHS certification. When
you have to ask your printing source in China if their inks are RoHS
compliant? That's fun.
On Thu, Nov 6, 2008 at 12:19 PM, Leonard C. Porrello <
Leonard -dot- Porrello -at- soleratec -dot- com> wrote:
> 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.porrello<techwr-l-bounces%2Bleonard.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
> >
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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-
