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.
Subject:Re: do you write or edit man pages? From:John Posada <jposada01 -at- yahoo -dot- com> To:Christi <christi -at- sageinst -dot- COM>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 11 Feb 2000 06:11:05 -0800 (PST)
If the pages, aside from the voice, are accurate and
the tech people find them useful, leave them alone.
I've done man pages, both as text and in troff.
There's more to man pages than voice. They can be very
technical instruments, and if you start playing with
the content, they will have to go through another
round of approval, editing, etc. Leave them alone.
They didn't ask for your involvement, you "asked for
them". So they are in passive voice? Pick your
windmills carefully.
--- Christi <christi -at- sageinst -dot- COM> wrote:
> Hi,
>
> I'm wondering if anyone writes or edits man pages as
> part of your job? The
> first new set of man pages was just released
> (internally), and I asked to
> see them. While they are generally ok; they are
> written in passive voice.
> This bothers me. Rather than say "the daemon should
> be stopped to determine
> the reason for lost contact", I'd rather it said
> "Stop the daemon to
> determine the reason for lost contact". Is it common
> for man pages to be in
> passive voice?
> Also, these pages are just a few new ones to a whole
> system. So, I'm sure
> the others are written as such. I'm not sure if it
> would be worthwhile to
> edit these when the rest of it won't match. But
> then, I think, if I don't
> start somewhere, they'll never get better.
> Does anyone who works with man pages have any
> thoughts?
>
=====
John Posada, Merck Research Laboratories
Sr Technical Writer, WinHelp and html
(work) john_posada -at- merck -dot- com - 732-594-0873
(pers) jposada01 -at- yahoo -dot- com - 732-291-7811
"When in trouble, when in doubt, run in circles, scream and shout."
__________________________________________________
Do You Yahoo!?
Talk to your friends online with Yahoo! Messenger. http://im.yahoo.com
