discuss: Offer of assistance/volunteering
Subject:
Re: Offer of assistance/volunteering
From:
Tabatha Marshall ####@####.####
Date:
4 Jun 2003 03:21:13 -0000
Message-Id: <1054696996.9939.263.camel@mysticchild>
On Tue, 2003-06-03 at 11:39, David Lawyer wrote:
> On Mon, Jun 02, 2003 at 05:56:09PM -0700, Tabatha Marshall wrote:
> > The process I've used is roughly this: When an author submits a brand
> > new document, we defer them to the discussion list to obtain feedback.
> > I usually ask that authors give that not longer than a week, and then
> > work in any feedback they feel would benefit the document.
>
> The problem with this is that it may often be the case that no one who
> gives feedback has actually read the document. Thus there is no feedback on
> most of the docs contents.
Joy defined this to me as "peer review" and it is something that I ask
every author to do upon a first submission. Since I've been doing it, I
have seen just about all of them receive feedback. Whether the
discussion list reads the drafts entirely or not, I'd be curious to
know.
> First, the review needs to be to some degree technical. Do the
> explanations make sense, etc.? Even if one doesn't know all the
> technical aspects, one can learn. For example, I'm about to review a
> Diskless Server HOWTO which was originally called the Dumb Terminal ...
> HOWTO. It seems to be based on the Linux Terminal Server Project
> (LTSP). So I went to the homepage of LTSP and read over the
> explanation of how a Terminal Server works using software supplied by
> LTSP. I skipped over all the details of how to install and configure it
> etc. Then I was able to see that the HOWTO's explanation of this was deficient.
Since I'm not always up to speed on some of the content in the HOWTOs I
review, I do rely to some degree on the peer review to handle some of
that. But wherever possible, such as Tille's Hands-on Guide, I found
myself trying out commands as I reviewed in order to verify things
worked as explained.
> I think that since we are behind, that to expedite reviews we should not
> read the entire document (unless it's short) and instead just sample
> parts of it for both technical and grammatical correctness. If the
> samples looks good, then accept the HOWTO. It doesn't need to be
> perfect. If the samples look bad, return it to the author, mentioning
> that the author is not to just correct the mistakes found in the
> sampling but to carefully go over the whole document. There will be
> borderline cases where one would need to sample more of it to get a
> better idea of what to do with it.
I have put the responsibility on the author to do many things, but
spelling and grammar are something Joy suggested I simply proceed with,
and I've always been fine with that. I just don't like to see documents
go up that aren't print quality, at least in terms of such basics.
> I don't think it really needs disclaimers in it. There's a saying that
> you don't look a gift horse in the mouth. And since our docs are a
> gift, one doesn't have much grounds to sue for errors. If an author
> intentionally misled readers, then I think that there would be grounds
> for a lawsuit. So in a way, it's better not to have disclaimers and
> put more responsibility on the authors.
I always thought disclaimers were more for applications, whereas the
license was ample to cover the document sufficiently - is that true?
BTW, I'm not trying to argue your very valid points, merely point out
what I was shown to do when I started at this. I am somewhat wary of
adding documents that haven't had a pair of human eyes to verify grammar
and spelling, but perhaps this is something that, as reviewers, we
should all be agreeing on.
Thanks!
Tabatha
--
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)
