Re: [PATCH v2 2/2] Documentation/sphinx: link dma-buf rsts

[Jonathan Corbet <corbet@lwn.net>]

On Tue, 23 Aug 2016 15:28:55 +0200
Daniel Vetter <daniel@ffwll.ch> wrote:

> I think the more interesting story is, what's your plan with all the
> other driver related subsystem? Especially the ones which already have
> full directories of their own, like e.g. Documentation/gpio/. I think
> those should be really part of the infrastructure section (or
> something equally high-level), together with other awesome servies
> like pwm, regman, irqchip, ... And then there's also the large-scale
> subsystems like media or gpu. What's the plan to tie them all
> together? Personally I'm leaning towards keeping the existing
> directories (where they exist already), but inserting links into the
> overall driver-api section.

To say I have a plan is to overstate things somewhat...

One objective I do have, though, is to declutter Documentation/.
Presenting people looking for docs with a 270-file directory is
unfriendly to say the least.  We don't organize the code that way; the
average in the kernel is <... find | wc -l ... > about 15
files/directory, which is rather more manageable.  Someday I'd like
Documentation/ to look a lot more like the top-level directory.

It seems to me that we have a few basic types of stuff here:

 - Driver API documentation, obviously, is a lot of it, and I would like
   to organize it better and to move it out of the top-level directory.

 - Hardware usage information - module parameters, sysfs files, supported
   hardware information, graphic descriptions of the ancestry of hardware
   engineers, etc.  The readership for this stuff is quite different, and
   I think it should be separate; often it's intertwined with API
   information at the moment.

 - Other usage information - a lot of what's under filesystems/ for
   example, and more.

 - Core API documentation.

 - Kernel development tools - the stuff I started pulling together into
   the dev-tools/ subdirectory.

 - How to deal with this unruly mob - SubmittingPatches, CodingStyle,
   development-process, etc.  There's process stuff, and general
   development documents like volatile-considered-harmful.txt or
   memory-barriers.txt

We can go a long way by organizing this stuff within the formatted
documentation, but I really think we need to organize the directory
structure as well.  I see that as a slow-moving process that will take
years, but I do think it's a direction we should go.

jon