Re: [PATCH] Re: Cleaning up the Documentation directory.

[Rob Landley <rob@landley.net>]

On Wednesday 23 May 2007 12:56 am, Paul Mundt wrote:
> On Wed, May 23, 2007 at 12:25:44AM -0400, Rob Landley wrote:
> >    mv arm cris blackfin parisc powerpc s390 x86_64 uml arch
> 
> You missed sh, mips, fujitsu/frv, m68k, ia64, i386, and sparc.

Yup.  I'll add 'em to the next pass.  Thanks.

There's plenty more to do.  (Why is smart-config.txt not in kbuild?  Why is 
rpc-cache.txt not in filesystems with nfs?  Why is xterm-linux.xpm in there 
at all, it's a graphic, not documentation...)  This was just me trying to 
figure out how to move files without big add/remove patches.  (I'd never set 
up git before, I use mercurial.)  A small and hopefully non-controversial 
set.

I'm trying to do a web version of the Documentation directory.  I've been 
reading through this on and off for a month now and I'm still trying to 
figure out where everything is.  The top level directory mixes together tons 
of obscure serial drivers, advice about how to submit, copies of standards 
documents like unicode.txt, administrative files like 
feature-removal-schedule.txt, debugging advice, userspace API documentation, 
datastructure documentation, design docs, a pointer to where to download the 
firmware for a Cyclades Z (still dunno what that is, but google probably 
would.  README.cycladesZ sure doesn't say...), historical notes like 
highuid.txt...

I'm also trying to figure out what is and isn't documented, so I can fill in 
some of the gaps.  (Or at least _identify_ them.)  Having a great unsorted 
heap of documentation doesn't help this, I need to categorize it to figure 
out the coverage.  (Let alone triaging the quality of what's there and 
figuring out if Linux Weekly News or Kerneltrap or somebodydid a way better 
writeup than what the kernel comes with, and maybe I can poke 'em into 
signing off on putting their version in the kernel.)

Yeah, I've got to read through "make htmldocs" too.  I'm working on it...

> Is there really enough documentation for these that another directory
> level is worthwhile?

You note that my first quick run-through missed half of this category of 
documentation, and then you ask whether or not the grouping is already 
obvious.  Yes, I think there's enough documentation to make another directory 
level worthwhile.

And as long as we're going there please explain why directories like "uml" 
and "telephony" only have one file each in them, but there's 
five "sched-*.txt" files at the root level?  Why is there an ioctl directory 
but ioctl-number.txt isn't in it?  (Maybe there are good answers for this 
other than "different people did different things without talking to each 
other, and documentation is an afterthought anyway".  I don't know.)

> 00-INDEX already covers most of these things, so 
> it's not like there's any measurable confusion..

Following that to its logical conclusion, why do we need subdirectories at 
all?  No, that's not sarcasm, I've actually pondered just making an 
index.html file that bears no relation to the underlying directory structure 
but lets people see "ok, these seven files are about locking, these six files 
are about the development model, these files describe development tools, this 
describes kernel infrastructure, these are busses, these are block 
devices..."

I thought reorganizing Documentation (so people who didn't already know 
everything in it could find things) would be more generally helpful, but if 
that's not the case I'm happy to do my own out-of-tree index instead.  Let me 
know what you prefer.

As to "why start here", the multiport serial drivers are each things that 99% 
of the audience will never use.  Few things even have serial anymore, those 
that do seldom use multiport cards, and when you _do_ have a multiport card 
you're looking for documentation on a specific one and the other half-dozen 
won't help you.  So having them at the root level is just clutter in anything 
remotely like the common case, and there's already a "serial" directory 
(another example of a directory with just one thing in it).

As for architectures, most people manage to avoid caring about the ones they 
don't use (as long as their changes don't break them, something they often 
can't test anyway).  Personally, I do embedded development and play with half 
a dozen architectures (plug: http://landley.net/code/firmware), but most 
people only look at one or two.  Files like "zorro.txt" are something that 
there are probably less than 100 people on the planet who still use it, which 
doesn't mean it's not _valuable_, just that having it at the root level is 
clutter to the vast majority of the userbase and arch/amiga seems like a 
better place for it.

Rob
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/