discuss: the good the bad and the ugly
Subject:
Re: the good the bad and the ugly
From:
Tabatha Marshall ####@####.####
Date:
19 Nov 2003 06:29:32 -0000
Message-Id: <1069223337.4047.95.camel@mysticchild>
On Tue, 2003-11-18 at 22:10, rahul wrote:
> i have no interest in an exact definition of good. what i want is segregation.
> Any outdated docs should be marked as such. any docs having potentially wrong
> information should be pulled out immediately. let me take a example of what i
> consider a good doc - the introduction to linux guide. Take a look at it. Not
> just the content, the way it is presented or even how docbook is used
> internally. Eric.S.Raymond's documents. Rusell's iptables howto. You will
> begin to see a pattern there. Take every doc i listed and go thru. do you
> find it satisfactory. I think people generally will agree that this is
> satisfactory. Now obviously all docs are not on the same level. it should be.
> lets move towards that. lets segregate first. Go through every single doc
> that you can in the ldp and present comments. lets discuss this and make a
> improvement. In about 2 to 3 months(what i have in mind) we should see marked
> improvements.
I don't really believe it's in our best interests to rip out every
document that is potentially erroneous. Many of these simply need
reviews, and the discussion list seems to be fired up with people who
are ready to assist with that.
A checklist was proposed. A good backend system can rate a document's
need for review based on such criteria. That will take a lot of the
manual work out of finding out which documents need the most work.
> After clearing all these docs we will have to work on screenings incoming
> stuff. every doc should go an technical as well as language review. we have
> reviewers who will take care of the language.
When at all possible (though perhaps idealistic) it would be nice to
coordinate a language review when a technical review takes place, unless
one has already been done fairly recently. However, if a tech review
prompted a significant amount of changes, it could always go through
another language review. This is why it would be helpful to the review
team for technical reviewers to post their results, for now, to the
author and on the editor's mailing list. If we see a tech review being
done, we can organize a language review as well, if needed.
> Technical reviewing is much more harder because it is likely to diversified.
> So we will have to rely on public feedback. We need to work on getting more
> feedback. This is what a content management system or wiki would give us. It
> would enable us the framework to recieve very quick feedback. Today I dont
> have a way to determine the quality of these docs. No statistics. which of
> the docs are being read more?. which of these docs are ignored. How do users
> feel about it. They will have to email the author for feedback which isnt the
> quick way to do it. We need the framework and we need it now.
No argument there! This is undoubtedly going to happen. Until then,
anyone with technical feedback can email the author, discussion list or
editor's list, and it can be looked at. We can add revision information
in the metadata reflecting tech reviews (we already do for language
reviews), so that readers can see for themselves that the material has
been kept up to date.
Tab
--
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)
