On 08/30/2012 05:21 PM, Robert P. J. Day wrote:
> 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?
Oh please no: http://xkcd.com/927/
And http://kernel.org/doc was initially an attempt to index the giant
pile of information available out on the net. Unfortunately the people
giving me time to do that decided they didn't like the idea..
> 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.
Any new directory would have just as much stuff in it. Splitting it
between two directories just makes the problem worse.
And what makes you think Documentation is the only source of
documentation in the tree? Even considering htmldocs as part of that
(despite parsing formatted comments in the source), there's menuconfig
help on all the config entries, there's README files scattered
throughout the tree, there's oddballs like "make help"...
I wrote a script to parse the source and find all the references to RFC
documents, producing html output ala:
http://kernel.org/doc/rfc-linux.html
The single digit ones are mostly false hits, which I need to go clean up...
> in a sense, Documentation/ is beyond redemption, so start fresh
> and have some rules to make sure stuff doesn't rot.
It's not beyond redemption. I am prepared to fix it. I just have to plow
through the ridiculous layers of bureaucracy the kernel.org guys put in
locking the barn door after the site got hacked.
> 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.
Git log should show you the author. I have a git tree that goes back all
the way to 0.0.1.) It would be up on kernel.org if they hadn't replaced
shell access with a hand-rolled "this does nothing but git" piece of
garbage that prevents me from doing an rsync. Meanwhile, it's here:
http://landley.net/kdocs/fullhist
> IMHO, there's no point trying to save Documentation/ -- just start
> fresh,
Been there, done that, I now understand why it didn't work.
(I.E. "So you _haven't_ read the OLS paper I linked to then.")
> lay down some rules, and build from scratch. then again, that
> might just be the wine talking.
It's the wine talking.
This exact same argument is made about _the_entire_kernel_ in the
embedded development community about twice a month. It always comes back
to Linux has 8 gazillion people submitting device driver support code to
it, and they go out of their way to make sure that this device driver
code is as unportable as humanly possible (not even to between dot
releases of the same project), so you have to take the whole bundle or
leave it if you want hardware support. In that regard, Linux bundles
more effectively than microsoft does. (There's a way to run windows
drivers under Linux.)
Rob
--
GNU/Linux isn't: Linux=GPLv2, GNU=GPLv3+, they can't share code.
Either it's "mere aggregation", or a license violation. Pick one.
--
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
