On Thu, 30 Aug 2012, Rob Landley wrote:
> On 08/29/2012 05:52 AM, Robert P. J. Day wrote:
> > i'm willing to help out since writing/editing is a big part of
> > what i do, and i'll repeat something i suggested a few days ago --
> > what Documentation/ needs *very* badly is a single file listing
> > the docs that are *obviously* out of date, plus whatever editorial
> > content someone wants to add that explains *what* is out of date
> > and any suggestions as to how it can be fixed.
>
> I'm all for it. What have you got so far?
not that much, i'm trying to submit patches to fix what i can for
now, but i'll start keeping track of what will be bigger necessary
changes.
> > everyone knows that lots of Doc/ is hopelessly old and
> > inaccurate, but in many cases, people simply don't have the time
> > to fix it.
>
> One of the things I was thinking of was having a directory structure
> under Documentation that mirrored the top level directories of the
> kernel source tree. Maybe
> Documentation/code/{block,crypto,fs,init...}
here's a thought -- why not start a new Doc/ directory, which will
slowly have content migrated over to it only after it's been vetted?
the problem with current Documentation/ is that there's so much
content there, it's impossible to tell what's useful and what's total
crap. in a sense, Documentation/ is beyond redemption, so start fresh
and have some rules to make sure stuff doesn't rot.
i think every file under a new Doc/ should have an author, or
*someone* to whom one could complain about being outdated. at the
very least, have a freaking last-modified date so one can tell it was
last changed in 2003 or something.
IMHO, there's no point trying to save Documentation/ -- just start
fresh, lay down some rules, and build from scratch. then again, that
might just be the wine talking.
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
