[RFC] Documentation dir is a mess

[RFC] Documentation dir is a mess

[Xose Vazquez Perez]

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

Re: [RFC] Documentation dir is a mess

[Greg KH]

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

thanks,

greg k-h

Re: [RFC] Documentation dir is a mess

[Steven Rostedt]

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

Re: [RFC] Documentation dir is a mess

[Marc Koschewski]

* Steven Rostedt <rostedt@goodmis.org> [2005-11-20 20:56:59 -0500]:

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

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

Re: [RFC] Documentation dir is a mess

[Matthew Frost]

--- Marc Koschewski <marc@osknowledge.org> wrote:

> * Steven Rostedt <rostedt@goodmis.org> [2005-11-20 20:56:59 -0500]:
> 
> > 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.
> 
> 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.

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

> 
> Marc
> -
> To unsubscribe from this list: send the line "unsubscribe linux-kernel"
> in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
> 

Re: [RFC] Documentation dir is a mess

[Paul Jackson]

> The documents
> that exist may not conform themselves well to that sort of division,
> necessarily.

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 <pj@sgi.com> 1.925.600.0401

Re: [RFC] Documentation dir is a mess

[Steven Rostedt]

On Tue, 22 Nov 2005, Paul Jackson wrote:

> > The documents
> > that exist may not conform themselves well to that sort of division,
> > necessarily.
>
> 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.
>

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

Re: [RFC] Documentation dir is a mess

[Paul Jackson]

Steve wrote:
> This would need to be done in a step by step basis.

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 <pj@sgi.com> 1.925.600.0401

Re: [RFC] Documentation dir is a mess

[Marc Koschewski]

* Matthew Frost <artusemrys@sbcglobal.net> [2005-11-21 22:06:48 -0800]:

> --- Marc Koschewski <marc@osknowledge.org> wrote:
> 
> > * Steven Rostedt <rostedt@goodmis.org> [2005-11-20 20:56:59 -0500]:
> > 
> > > 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.
> > 
> > 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.
> 
> 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.

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

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

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

> 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

[RFC PATCH] was Re: [RFC] Documentation dir is a mess

[Xose Vazquez Perez]

Greg KH wrote:

> On Sun, Nov 20, 2005 at 01:19:09PM +0100, Xose Vazquez Perez wrote:

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

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

Re: [RFC] Documentation dir is a mess

[Rob Landley]

On Sunday 20 November 2005 06:19, 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:
>
> Documentation/
> Documentation/arch/
> Documentation/arch/i386/
> [...]
> Documentation/drivers/
> Documentation/drivers/net/
> Documentation/drivers/scsi/
> [...]
> Documentation/net
> [...]

Perhaps you're looking for "make htmldocs"?

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

Rob

Re: [RFC] Documentation dir is a mess

[Christopher Friesen]

Rob Landley wrote:
> On Sunday 20 November 2005 06:19, Xose Vazquez Perez wrote:

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

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

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

> Documentation/filesystems/proc.txt?

This one seems obvious:

Documentation/fs/proc.txt

Chris

Re: [RFC] Documentation dir is a mess

[Rob Landley]

On Monday 21 November 2005 10:44, Christopher Friesen wrote:
> > Documentation/filesystems/proc.txt?
>
> This one seems obvious:
>
> Documentation/fs/proc.txt

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

Re: [RFC] Documentation dir is a mess

[Christopher Friesen]

Rob Landley wrote:

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

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

Re: [RFC] Documentation dir is a mess

[Jiri Slaby]

Rob Landley napsal(a):

>On Sunday 20 November 2005 06:19, 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:
>>
>>Documentation/
>>Documentation/arch/
>>Documentation/arch/i386/
>>[...]
>>Documentation/drivers/
>>Documentation/drivers/net/
>>Documentation/drivers/scsi/
>>[...]
>>Documentation/net
>>[...]
>>    
>>
>
>Perhaps you're looking for "make htmldocs"?
>  
>
This is not, what he wants.

>Where would you put Documentation/unicode.txt in your proposed layout?  Or
>  
>
Documentation/others? or sth.

>Documentation/filesystems/proc.txt?
>  
>
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
\_.-^-._   jirislaby@gmail.com   _.-^-._/
B67499670407CE62ACC8 22A032CC55C339D47A7E

Re: [RFC] Documentation dir is a mess

[Xose Vazquez Perez]

Rob Landley wrote:

> Perhaps you're looking for "make htmldocs"?

No.

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

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