Documentation dir is a mess

hi,

_today_ Documentation/* is a mess of files. It would be good to have the _same_ tree as the code has:

Documentation/
Documentation/arch/
Documentation/arch/i386/
[...]
Documentation/drivers/
Documentation/drivers/net/
Documentation/drivers/scsi/
[...]
Documentation/net
[...]

-thanks-

Romanes eunt domus

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...

thanks,

greg k-h

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

As you're just about to maybe make a decision on reorganisation: how about a separation of user- and developer-relevant documentation? I mean, kernel boot parameters are relevant to a user whereas mm/* stuff is not.

Marc

There's a problem in the general conception that user/developer is a mutex. The whole idea is that anyone may become a developer at will. A division of Documentation/ to make an artificial distinction that the community doesn't necessarily believe in doesn't seem too useful.

Now, I don't mean to suggest that you're wrong; I'm sure you have a valid point. If I may rephrase, it sounds more like you're looking for "fingertip reference" versus "in-depth documentation". The documents that exist may not conform themselves well to that sort of division, necessarily. However, I'm sure that there exist fingertip references outside of Documentation/ and the kernel tree; many of them are for 'newbies'.

Is this a useful interpretation? Would an incorporation of this sort of functional division meet your request? Does anyone have the time to devote to it? Am I just reading out of the bit bucket?

Matt

Good point, not just for -that- sort of division, but perhaps for any sort.

I am skeptical that there is much value to be added to the current hodge podge of documents in the Documentation directory by rearranging them in some grand scheme.

Certainly there is some value that can be subtracted -- just changing it will result in some minor cost to each of us, adjusting to the changes. The greater the changes, the more aggressive the effort to categorize it, the greater this distributed cost of change.

Perhaps what we have is deeper than just improperly arranged Docs. The content of the Docs may have too much variation in depth, topic, breadth, organization, style and such to be well suited to a deep structure.

Maybe it looks disorganized because it is -- more than just skin deep.

                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <[email protected]> 1.925.600.0401

Exactly why the documents _should_ be rearranged. If you expect the contents of the documents to be cleaned up first, that wont happen. But if you make an hierarchy out of the current Document design (which there is some attempt to do so already there), then later changes can be to start breaking up the documents that have too much at every level into smaller versions where they belong.

So the hierarchy can be like an outline. The first stab at this should just be to make the catagories that are needed, and still allow those catagories themselves be able to change. Then, if necessary, modify the documents.

This would need to be done in a step by step basis. Although the first round can be the creation of the document directories with the attempt of placing every document in the toplevel Document directory into a lower directory. Then we can slowly start fixing them one by one.

Like I said, I would be willing to start reading each document and see where it might fit. You may not agree with my decision, but then we can discuss it and find a proper fit.

So the question remains, how does one start this? Should someone just take a crack at it, submit it, and then let the games begin?

-- Steve

True. Good points. If this directory reorg is part of a larger effort to improve the Doc subtree, and someone is intending to put in that effort and will do a good job, then more power to them.

If it's just a one time rearrangement of the existing docs, then it would likely be more nuisance than value.

                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <[email protected]> 1.925.600.0401

Sure, a developer is always a user. But even if so, we could, however, split some docs into a developer and an end-user part. Configuring PCMCIA doesn't mean I wanted to be 'bothered' by some internals of the implementation.

What about a such an approach?

Documentation/howto/.../...
Documentation/howto/pcmcia/...
Documentation/howto/.../...
Documentation/dev/...
Documentation/dev/pcmcia/...
Documentation/dev/...

Most docs out there one may find through Google or whatever mostly hit one particular case. Ie. 'PCMCIA networking device on DELL Inspiron 8200' and not just a common information on how PCMCIA networking is setup in userland.

Moreover, having such information within the Documentation tree would make sense as a user has information on how to _use_ a sub-system right when she _enables_ the sub-system (via new kernel installation).

If the docs would be in a commonly used form (Headlines, prerequisites [tools], ...) it would just be a benefit.

Besides this, it would be nice to reflect the source tree just _a bit_ within the Documentation tree - ie. create a Documentation/drivers dir within information on drivers along with their supported devices in a human readable form (no device IDs) and the params the module is able to handle. Sure, there's 'modinfo'. But let's have a look ...

['sg' is just a common module, no particular reason I took this one]

marc@stiffy:~$ modinfo sg
filename:       /lib/modules/2.6.15-rc2-marc/kernel/drivers/scsi/sg.ko
author:         Douglas Gilbert
description:    SCSI generic (sg) driver
license:        GPL
version:        3.5.33
alias:          char-major-21-*
vermagic:       2.6.15-rc2-marc preempt PENTIUM4 gcc-4.0
depends:        scsi_mod
srcversion:     B8A3D2FFE5BA5BB2348A9AC
parm:           allow_dio:allow direct I/O (default: 0 (disallow)) (int)
parm:           def_reserved_size:size of buffer reserved for each fd
(int)
marc@stiffy:~$

What does a non-developer get out of 'allow direct I/O'?
- What id direct I/O?
- How does it affect performance?
- What are the common pitfalls?
- Why do I have the choice at all?

What does a non-developer get out of 'size of buffer reserved for each fd'?
- What is a buffer?
- What size is best? Rather small? Rather big? Dependant on my system?
- What are the common pitfalls?
- Why do I have the choice at all?

There are things to answer. And not Google does answer these question. Most users (and even more the newbies) are unable to get such information out of Google. I know people having PCs (with or without Linux) who are unable to get any relevant technical information out of Google although they used computers for years now.

Marc

well, more or less the same but not _exactly_ the same ;-)

I already have a big patch against 2.6.15-rc2-git5:

[ http://perso.wanadoo.es/xose_vp/documentation_cleanup_01.diff.bz2 ]

main features:
- move all drivers_info into 'drivers'
- move all arch_info into 'arch'
- move all drivers_info from 'net' to 'drivers/net'

TODO:
- clean up the 'Documentation' root dir a bit more (easy)
- remove (easy) or update all INDEX files (tedious)
- move all info/text files from source code to 'Documentation' dir (tedious)
- verify all files are in the correct place (tedious)

enough for now.

-thanks-

Romanes eunt domus

Perhaps you're looking for "make htmldocs"?

Where would you put Documentation/unicode.txt in your proposed layout? Or Documentation/filesystems/proc.txt?

Rob

One logical place would be to leave stuff that applies to the whole tree at the top level. Thus, it would just stay "Documentation/unicode.txt".

This one seems obvious:

Documentation/fs/proc.txt

Chris

Except that I picked proc.txt because the contents of the file are really about the whole source tree. (This isn't documentation about the proc filesystem infrastructure, it's documentation about all known users of that infrastructure...)

Again, doesn't quite clearly map onto a location in the source tree...

Rob

This depends on how you're looking at it.

Documentation/filesystems/proc.txt is written from a "user" perspective, not a "kernel developer" perspective.

From the user perspective, this file documents the contents of "/proc" which is one single place.

Chris

Rob Landley napsal(a):

This is not, what he wants.

Documentation/others? or sth.

It is somewhere, why to move it, simply rename the directory to fs, as he mentioned.

Sorting is not a problem in my opinion. If no other problem occurs, it sounds good to me.

regards,

Jiri Slaby         www.fi.muni.cz/~xslaby
\_.-^-._   [email protected]   _.-^-._/
B67499670407CE62ACC8 22A032CC55C339D47A7E

No.

If there is not a new good place, let it be. We need to be good, not perfect.

Maybe this idea would be the next entry in the "Christmas list for the kernel" after:

(5) a pony

(6) world peace

;-)

Romanes eunt domus