Re: [RFC] Documentation dir is a mess

[Steven Rostedt <rostedt@goodmis.org>]

On Sun, 2005-11-20 at 16:30 -0800, Greg KH wrote:
> On Sun, Nov 20, 2005 at 01:19:09PM +0100, Xose Vazquez Perez wrote:
> > hi,
> > 
> > _today_ Documentation/* is a mess of files. It would be good
> > to have the _same_ tree as the code has:
> 
> Do you have a proposal as to what specific files in that directory
> should go where?  Just basing it on the source tree will not get you
> very far...

Actually I think it's a good start.  When I'm looking for documentation,
I usually just do a grep -r on the Documentation directory hoping I get
a correct hit and then manually look through all the results I get.  It
does get tedious, and I miss things all the time.

So how about something like the following:

Documentation/kernel:
  Holds things like atomic_ops.txt, cpusets.txt cpu-freq(dir),
kobjects.txt (etc).

Documentation/fs:
  (already a filesystems directory)

Documentation/crypto:
  (also already there)

Documentation/drivers:
  breaking this up to all the files that deal with specific functions in
the drivers directory (like tty.txt, video4linux, etc)

Documentation/arch:
  Each arch can have its own directory.

Documentation/net:
  Network stuff

Documentation/mm:
  memory management stuff

And etc, etc, for all in the main directory.

What would need to be done is look at each file already in Documentation
and see where it should go and put it there.  The actual Documentation
directory should have no text files and only directories, with the
exception of documentation explaining how the Documentation directory is
ordered.

Also, this doesn't need to be limited to the kernel hierarchy
directories, but also directories like:

Documentation/build:
  how to build the kernel

Documentation/debug:
  debugging options

Documentation/development
  things that may help out new developers.

And whatever else can be thought of.

If something like this _is_ desired, I wouldn't mind spending some extra
free time reading each of the files in documentation and ordering them
(I might actually learn something doing this too :-).

-- Steve