discuss: Re: Beginning of outline for policies
Subject:
Re: Fwd: Beginning of outline for policies
From:
David Lawyer ####@####.####
Date:
20 Jun 2002 14:46:56 -0000
Message-Id: <20020620003821.B1788@lafn.org>
On Tue, May 21, 2002 at 10:05:41PM -0600, ####@####.#### wrote:
> On Sun, May 19, 2002 at 10:00:40AM +0200, jdd wrote:
> >
> > if the reviewer is so good as to be able to edit a HOWTO, why don't
> > he write it himself? and if he is not what is he doing?
>
> Writing, reviewing and editing are very different skills. they
> compliment each other.
>
> Writing involves imagination, organization skills, the abilities to do
> research and to interview people, the ability to convey information
> accurately and concisely, and some familiarity with the subject. He
> does not have to be expert in it. Often, a lack of expertise lets the
> writer ask questions that someone in the field won't ask -- often
> exactly the sort of questions the audience will ask. When I worked at
> HP, I worked with a technical writer who described himself in his sig
> line as a "computer information detective." I think that's a very good
> description.
>
> An editor should have some knowledge of the language and how it is
> used to convey information. A technical editor has to have a good
> grasp of the subject's argot.
The technical editor needs to know the topic so that she can tell if
important areas have been omitted, if the procedures described are the
most efficient, if the theory is explained correctly, etc.
I think jdd's point was that in view of the pressing need for certain
HOWTOs, a technical editor might better spend her time by actually
writing a HOWTO. I think this is a good point for cases where readers
supply good technical feedback. If they don't, then such a doc needs
technical review. Technical review works good where a doc just has a
relatively small number of errors. This will not take much time to
review. But if it has a lot of problems, then a technical reviewer
might better spend her time rewriting the entire doc. It is a waste of
effort to spend about as much time reviewing a doc as it took to write
it.
> A reviewer, as we are using the term here, should be technically aware
> in the field under discussion, but need not know how to write or edit.
True, but the LDP shouldn't need to do this much. Readers of the doc
who read it over to learn can also give review-like feedback. I've
gotten some of this.
> > I think it's possible to scan a doc fast for minimal correctness of
> > language and spell, thats all. this could barely take more than an
> > hour.
Good point. I think that we should do this first for all docs if
possible. We should also encourage authors to put a statement in the
doc asking that readers send feedback to the author.
>
> That depends on the document and the level of quality desired. A good
> technical editor may spend up to an hour per typeset page. I know;
> I've gotten the bleeding corpses back from editors. :-)
> >
> > there are too much unsupported areas around. It should be better to
> > write doc than search problems with authors.
I tend to agree. A problem is that if a doc is really bad, like Al
Dev's PHP-HOWTO, readers will not even bother to let the author know
about all the things wrong with it. To do so they would have to almost
rewrite the entire document. So we need to have a minimal review of all
new docs to keep such poorly written docs out of LDP.
[snip]
I've suggested before that LDP have topic coordinators with each
handling say 10-40 HOWTOs on a certain topic. There could be a
network-coordinator, a modem-coordinator, etc. The coordinator would
review all the HOWTOs in his topic. She might be the author of one of
these HOWTOs. She could suggest splitting up of HOWTO or merging them
and would make sure that the Category Index had them all listed under
the appropriate categories.
David Lawyer
