Re: do you write or edit man pages?

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.

Previous by Author: Re: "site sucker"
Next by Author: Re: Problems Documenting An Application
Previous by Thread: do you write or edit man pages?
Next by Thread: RE: do you write or edit man pages?

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

Sponsored Ads

Sponsored Ads