Structural changes for Documentation directory
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.
Quoted 2 lines · Jim Nelson
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
Signature · 7 lines
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.
Quoted 11 lines · Nigel Cunningham
Hi.
Quoted 2 lines · Jim Nelson
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 ?
Signature · 2 lines
Måns Rullgård [email protected]
Quoted 3 lines · Jim Nelson
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.
Quoted 3 lines
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.
Quoted 5 lines · Andrew Morton
Quoted 1 line · Jim Nelson
I propose changing the structure of the Documentation directory to reflect the structure of the kernel sources itself.
Quoted 10 lines
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.
Quoted 9 lines
Quoted 1 line
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
Quoted 3 lines · Jim Nelson
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
Quoted 6 lines · Dave Jones
Quoted 3 lines · Jim Nelson
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.
Quoted 7 lines
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
Quoted 21 lines · Jim Nelson
Quoted 6 lines · Dave Jones
Quoted 3 lines · Jim Nelson
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.
Quoted 7 lines
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.
Quoted 5 lines
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.
Quoted 5 lines · Andrew Morton
Quoted 3 lines
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
Quoted 6 lines · Dave Jones
Quoted 4 lines · Andrew Morton
Quoted 3 lines
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.
Quoted 6 lines
Quoted 1 line
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.
Quoted 5 lines · Dave Jones
Quoted 4 lines · Andrew Morton
Quoted 3 lines
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.
Quoted 9 lines
Quoted 1 line
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