[RFC] Structural changes for Documentation directory

[RFC] Structural changes for Documentation directory

[Jim Nelson]

I propose changing the structure of the Documentation directory to 
reflect the structure of the kernel sources itself.

How I see it working is: (Excuse the ASCII-art)

Documentation/
    |
    |____ arch/
    |      |
    |      |____ i386/
    |      |
    |      |____ s390/
    |      |
    |      |____ (etc.)
    |
    |____ drivers/
    |      |
    |      |____ cdrom/
    |      |
    |      |____ serial/
    |      |
    |      |____ (etc.)
    |
    |____ net/
    |      |
    |      |____ sunrpc/
    |      |
    |      |____ atm/
    |      |
    |      |____ (etc.)
    |
    |____ kernel/
    |
    |____ mm/

With the files that have no real home in the source (SubmittingPatches, 
CodingStyle, kernel-docs.txt, etc) to remain in the main directory.

Perhaps it would be best to put the new tree in place and have the 
individual maintainers relocate their documentation to the new 
structure?  This would also be a good way to find out what files are 
orphaned, and are in need of update or removal.

Comments?  Additions?  Warnings?

Re: [RFC] Structural changes for Documentation directory

[Nigel Cunningham]

Hi.

On Thu, 2004-10-21 at 06:51, Jim Nelson wrote:
> I propose changing the structure of the Documentation directory to 
> reflect the structure of the kernel sources itself.

It seems that people know where to find the source code for whatever
they're seeking documentation for. If I didn't work on the code, I
wouldn't look for suspend-to-{disk|ram} under kernel/. I have to admit,
it's always seemed strange to me, too, that net and sound aren't under
drivers :>

Nigel
-- 
Nigel Cunningham
Pastoral Worker
Christian Reformed Church of Tuggeranong
PO Box 1004, Tuggeranong, ACT 2901

Many today claim to be tolerant. True tolerance, however, can cope with others
being intolerant.

Re: [RFC] Structural changes for Documentation directory

[Måns Rullgård]

Nigel Cunningham <ncunningham@linuxmail.org> writes:

> Hi.
>
> On Thu, 2004-10-21 at 06:51, Jim Nelson wrote:
>> I propose changing the structure of the Documentation directory to 
>> reflect the structure of the kernel sources itself.
>
> It seems that people know where to find the source code for whatever
> they're seeking documentation for. If I didn't work on the code, I
> wouldn't look for suspend-to-{disk|ram} under kernel/. I have to admit,
> it's always seemed strange to me, too, that net and sound aren't under
> drivers :>

drivers/net ?

-- 
Måns Rullgård
mru@mru.ath.cx

Re: [RFC] Structural changes for Documentation directory

[Andrew Morton]

Jim Nelson <james4765@verizon.net> wrote:
>
> I propose changing the structure of the Documentation directory to 
> reflect the structure of the kernel sources itself.

That sounds like a bit of overdesign, really.  Take it one step at a time.

Sure, if you're really prepared to do a large-scale overhaul then the first
step is to create a new top-level directory, say
"./non-crappy-Documentation" and then move files over into there as they
are fixed up.  That way we have a good handle on what is done and what
remains.  You can then make decisions about the directory structure
on an incremental basis as you become more familiar with the problem.

> Perhaps it would be best to put the new tree in place and have the 
> individual maintainers relocate their documentation to the new 
> structure?

Maintainers studiously ignore the Documentation directory.  If someone
really wishes to get in there and fix it all up, that person gets to decide
what goes where and that person gets to harrass various other maintainers
when assistance is needed.

Re: [RFC] Structural changes for Documentation directory

[Jim Nelson]

Andrew Morton wrote:
> Jim Nelson <james4765@verizon.net> wrote:
> 
>>I propose changing the structure of the Documentation directory to 
>>reflect the structure of the kernel sources itself.
> 
> 
> That sounds like a bit of overdesign, really.  Take it one step at a time.
> 
> Sure, if you're really prepared to do a large-scale overhaul then the first
> step is to create a new top-level directory, say
> "./non-crappy-Documentation" and then move files over into there as they
> are fixed up.  That way we have a good handle on what is done and what
> remains.  You can then make decisions about the directory structure
> on an incremental basis as you become more familiar with the problem.
> 
> 

True.  "./2.6-docs" would reflect the the intent of having 
version-specific information, with the "./Documentation" directory left 
for general information and files of historical interest.

>>Perhaps it would be best to put the new tree in place and have the 
>>individual maintainers relocate their documentation to the new 
>>structure?
> 
> 
> Maintainers studiously ignore the Documentation directory.  If someone
> really wishes to get in there and fix it all up, that person gets to decide
> what goes where and that person gets to harrass various other maintainers
> when assistance is needed.
> 
> 

Well, it is necessary.  Probably the best job for a polite Southern boy 
like me :D

Re: [RFC] Structural changes for Documentation directory

[Dave Jones]

On Wed, Oct 20, 2004 at 06:51:04PM -0400, Jim Nelson wrote:

 > True.  "./2.6-docs" would reflect the the intent of having 
 > version-specific information, with the "./Documentation" directory left 
 > for general information and files of historical interest.

version numbers in directories are nearly always a bad idea,
as they always tend to look a bit silly when the subsequent
release is made.

		Dave

Re: [RFC] Structural changes for Documentation directory

[Jim Nelson]

Dave Jones wrote:
> On Wed, Oct 20, 2004 at 06:51:04PM -0400, Jim Nelson wrote:
> 
>  > True.  "./2.6-docs" would reflect the the intent of having 
>  > version-specific information, with the "./Documentation" directory left 
>  > for general information and files of historical interest.
> 
> version numbers in directories are nearly always a bad idea,
> as they always tend to look a bit silly when the subsequent
> release is made.
> 
> 		Dave
> 
> 

But it would also give a clue that the docs are out of date.  Perhaps 
later in each developement cycle, there could be an effort to check the 
documentation, with a 2.8-docs or 3.0-docs being the result, and dumping 
the 2.6-docs into the historical reference directory.

Or, the old stuff could be dropped with the new stable release.

The other possibility is to have a TODO file with a list of out-of-date 
files, and have the removal of the file listing in the TODO file be part 
of the patch submission.

Jim

Re: [RFC] Structural changes for Documentation directory

[Andrew Morton]

Jim Nelson <james4765@verizon.net> wrote:
>
> Dave Jones wrote:
>  > On Wed, Oct 20, 2004 at 06:51:04PM -0400, Jim Nelson wrote:
>  > 
>  >  > True.  "./2.6-docs" would reflect the the intent of having 
>  >  > version-specific information, with the "./Documentation" directory left 
>  >  > for general information and files of historical interest.
>  > 
>  > version numbers in directories are nearly always a bad idea,
>  > as they always tend to look a bit silly when the subsequent
>  > release is made.
>  > 
>  > 		Dave
>  > 
>  > 
> 
>  But it would also give a clue that the docs are out of date.  Perhaps 
>  later in each developement cycle, there could be an effort to check the 
>  documentation, with a 2.8-docs or 3.0-docs being the result, and dumping 
>  the 2.6-docs into the historical reference directory.
> 
>  Or, the old stuff could be dropped with the new stable release.
> 
>  The other possibility is to have a TODO file with a list of out-of-date 
>  files, and have the removal of the file listing in the TODO file be part 
>  of the patch submission.

It all sounds too complex.  ./docs/ is fine.

Re: [RFC] Structural changes for Documentation directory

[Dave Jones]

On Wed, Oct 20, 2004 at 10:00:37PM -0700, Andrew Morton wrote:
 > >  The other possibility is to have a TODO file with a list of out-of-date 
 > >  files, and have the removal of the file listing in the TODO file be part 
 > >  of the patch submission.
 > 
 > It all sounds too complex.  ./docs/ is fine.

asides from bloating up interdiffs, what does moving stuff around
gain us over just fixing stuff in place ?  Do we really have
that much out of date documentation to justify this ?

		Dave

Re: [RFC] Structural changes for Documentation directory

[Andrew Morton]

Dave Jones <davej@redhat.com> wrote:
>
> On Wed, Oct 20, 2004 at 10:00:37PM -0700, Andrew Morton wrote:
>  > >  The other possibility is to have a TODO file with a list of out-of-date 
>  > >  files, and have the removal of the file listing in the TODO file be part 
>  > >  of the patch submission.
>  > 
>  > It all sounds too complex.  ./docs/ is fine.
> 
> asides from bloating up interdiffs, what does moving stuff around
> gain us over just fixing stuff in place ?  Do we really have
> that much out of date documentation to justify this ?
> 

Well I was thinking of it as a simple way of tracking what has and hasn't
been done.  But yeah, that could just as easily be tracked via a new
checklist file.

Re: [RFC] Structural changes for Documentation directory

[Jim Nelson]

Dave Jones wrote:
> On Wed, Oct 20, 2004 at 10:00:37PM -0700, Andrew Morton wrote:
>  > >  The other possibility is to have a TODO file with a list of out-of-date 
>  > >  files, and have the removal of the file listing in the TODO file be part 
>  > >  of the patch submission.
>  > 
>  > It all sounds too complex.  ./docs/ is fine.
> 
> asides from bloating up interdiffs, what does moving stuff around
> gain us over just fixing stuff in place ?  Do we really have
> that much out of date documentation to justify this ?
> 
> 		Dave
> 
> 
Well, before I started this thread, I actually looked through the root 
Documentation directory, taking notes, and there were 40 files that were 
definitely out of date, and 10 that were not obviously out of date, but 
had no indication that it had been updated recently.

That's without digging into the subdirectories.

Jim