Elyse M. Grasso said: > Is there something I could do to help? It's been years since I programmed > C, but I'm a former librarian, current configuration management tools > consultant. I write good standards-compliant HTML and XHTML, and Perl is my > life these days. > > Point me at something where I won't be duplicating effort and I'll take a > look at it. > -- > Elyse Grasso Ok, here's what I've got at the top of my todo heap. My first priority is a massive indexing job. I have a half-dozen sources of information either mirrored or linked from "http://kernel.org/doc"; already, and before I add more I'd like to integrate the ones I've got into one big index, sorted by topic. I appended the skeleton of a possible index to the page, and I'd like to start by shuffling in articles from Documentation, the lwn.net kernel page, and the broken-up OLS papers I've mirrored on the site. These are probably the three highest quality sources of documentation with a reasonable granularity to the information. (The man pages are very good too, but the man page maintainer expressed interest in maintaining his own html versions online, and I'd like to give that time to settle before linking to a location that might move.) Today I'm going through OLS papers from 2002. I'm reading them all and writing one paragraph summaries, which I can then use to slot them into the index on a second pass. It's possible that not every entry will wind up in the index. I'm interested in retaining historical material (how did we wind up where we are?), but some things like the penguin logo graphic in Documentation/xterm-linux.xpm I just don't care about. (I'd rather link to the "history of tux" page and larry ewing's page with the original graphics.) If a paper is in archive.org we don't need a local mirror. If it isn't, we should have at least a private one which we can figure out what to do about if/when the upstream site goes down. There are a lot more things that need to be indexed. With some of them the granularity's wrong, such as the Linux Device Drivers books. (Excellent material, but how do you link into the middle of it?) Many things have their _own_ topic indexes, which don't integrate well with any of the others. Another thing to think about is figuring out how stale/current stuff is. For Documentation/* we're going to refresh with every kernel release (and eventually run a 404 checker to find dead links), and leave that to the upstream maintainers. (I have some cleanup patches I can push for that too, but it's not a priority until I get the rest under control.) Magazine articles in LWN or linux journal have dates, as do developer's blog entries and OLS papers. One easy thing we can do is under each topic, sort the references by date so the newest ones come first and the oldest ones are at the end. If we want more than that, we can give the topic its own sub-page. Don't be afraid to link articles from multiple places if they cover, say, the interaction of the memory management system with the virtual file system. Lots of this stuff overlaps. Beyond that, there's a ton of stuff to do. Some of my todo notes are at "http://landley.net/kdocs/pending/todoc.txt";. You'll notice I haven't seriously addressed the "make htmldocs" output yet (GIANT EVIL PERL REGEX! AAAAAAH!) I have a patch to make one big html page per book instead of lots of little ones, but haven't figured out which would be the more useful format to try to put up and index. I do know that the "lots of little ones" changes the produced pages with every version so you can't easily link to them stably, but the one big page version changes the #anchor tags too. Possibly the sections can be named stably somehow?) That's what I'm thinking. Anything jump out as interesting, or wrongheaded? Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - 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
