On 08/29/2012 05:52 AM, Robert P. J. Day wrote:
> On Tue, 28 Aug 2012, Rob Landley wrote:
>> This is _my_ problem not yours, and since then I've made some
>> progress on it. It's just... got me off to a slow start. To be
>> honest, I've been funneling stuff through trivial@xxxxxxxxxx since
>> the nice maintainer there was kind enough to host things in a way
>> Linus will pull. But the big cleanups (collating the translations
>> under a common directory, collating the architectures under a common
>> directory) require me to have a git tree with the appropriate magic
>> blessing sucked into linux-next, so...
Sigh. One of the first things I need to do is push some X: lines to
MAINTAINERS to cut down the noise on linux-doc (it's parsed by
scripts/bother-people.pl to come up with the cc: spam for patches) so I
can actually keep up with the thing. (Stuff I'm cc'd on I've got 400
unread messages. linux-doc I've got 2000.)
> 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?
I've been focusing on trying to index/sort what's there into some sort
of vaguely coherent order. I haven't actually managed to read it all yet.
I'm trying to take next week off from work, and getting a reasonable
handle on my Documentation responsibilities is my priority for that time.
> 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...}
I'm also looking at what I can check mechanically. If there are multiple
obvious places for a document to hide, I could put a symlink, because
checking for broken symlinks is trivial. I've already got a script that
checks for missing or stale 00-INDEX entries (which gives me a giant
list I need to act on...)
> what
> people *do* have the time for, however, is the minute or two it takes
> to simply *state* that something is too old to have any value, perhaps
> adding another sentence or two as to where better documentation is, or
> how the current file can be improved. and in some cases, pointers
> that some files can simply be tossed as useless.
Did you ever read my write-up of my first stab at this?
Where Linux kernel Documentation hides:
http://kernel.org/doc/ols/2008/ols2008v2-pages-7-18.pdf
(Something I didn't quite cover in there was why wikis are less help
than you'd think. Wikis are great at holding a slush pile, but suck at
indexing it. Wikipedia can't tell a story, the closest you get is
tvtropes.com.)
> i'm sure a lot of people who want to help improve the docs simply
> don't have the time to do it themselves. but they're happy to at
> least point out when something is desperately in need of updating.
>
> thoughts? how can we get this started?
I'd love to harness the help of anybody who can spare the enthusiasm.
My own plan of attack was to start by _moving_ existing documentation.
I'd like to put the architecture-specific documentation under an "arch"
subdirectory, and the non-english documentation under "translations",
and group all the introductory/policy/political documents somehow.
This isn't actually changing any of the files, so if you want to index
them based on currency and relevance, we can do that in parallel for a
bit without interfering with each other.
> rday
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
