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?
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.
Jim Nelson <[email protected]> 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.
Nigel Cunningham <[email protected]> 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
[email protected]
Andrew Morton wrote:
> Jim Nelson <[email protected]> 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
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
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
Dave Jones <[email protected]> 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.
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
Jim Nelson <[email protected]> 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.
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