discuss: the good the bad and the ugly
Subject:
Re: the good the bad and the ugly
From:
rahul ####@####.####
Date:
19 Nov 2003 06:10:36 -0000
Message-Id: <200311191140.22892.rahulsundaram@yahoo.co.in>
On Wednesday 19 November 2003 08:42, Tabatha Marshall wrote:
> On Tue, 2003-11-18 at 19:04, David Horton wrote:
> > What are the criteria for "good docs"? Is it anything not outdated or
> > is content being judged as well?
>
> I suppose any answer would be somewhat subjective, but here goes... :D
>
> I would say anything that has been technically reviewed for accuracy,
> reviewed for language (spelling, grammar, clarity), contains links for
> readers to get more information, shows alternative methods to accomplish
> the task, if available (depending on the scope), and clearly meets the
> defined scope, would be indicative of a "good" doc.
>
> In other words, if you tell us we can do something by the end of the
> HOWTO, we better be able to do it! :D
>
> Again, subject to opinion. There are many components that make up a
> good document. The above are some of the things I consider criteria for
> a work being submitted.
>
> Tab
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.
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.
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.
regards
Rahul Sundaram
regards
rahul sundaram
