Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: David Howells <dhowells@redhat.com>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Linux MM <linux-mm@kvack.org>,
	Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
	Asmaa Mnebhi <Asmaa@mellanox.com>,
	Vladimir Oltean <olteanv@gmail.com>
Subject: Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
Date: Wed, 19 Jun 2019 12:54:10 -0300	[thread overview]
Message-ID: <20190619125410.6da59ea6@coco.lan> (raw)
In-Reply-To: <20190619085458.08872dbb@lwn.net>

Em Wed, 19 Jun 2019 08:54:58 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> [Trimming the CC list from hell made sense, but it might have been better
> to leave me on it...]
> 
> On Wed, 19 Jun 2019 11:15:28 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > Em Wed, 19 Jun 2019 14:39:10 +0100
> > David Howells <dhowells@redhat.com> escreveu:
> >   
> > > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > >     
> > > > > > -Documentation/nommu-mmap.rst
> > > > > > +Documentation/driver-api/nommu-mmap.rst        
> > > 
> > > Why is this moving to Documentation/driver-api?      
> > 
> > Good point. I tried to do my best with those document renames, but
> > I'm pretty sure some of them ended by going to the wrong place - or
> > at least there are arguments in favor of moving it to different
> > places :-)  
> 
> I think that a lot of this might also be an argument for slowing down just
> a little bit.  I really don't think that blasting through and reformatting
> all of our text documents is the most urgent problem right now and, in
> cases like this, it might create others.
> 
> Organization of the documentation tree is important; it has never really
> gotten any attention so far, and we're trying to make it better.  But
> moving documents will, by its nature, annoy people.  We can generally get
> past that, but I'd really like to avoid moving things twice.  In general,
> I would rather see a single document converted, read critically and
> updated, and carefully integrated with the rest than a hundred of them
> swept into different piles...
> 
> See what I'm getting at?

I see what you mean, and I agree with this principle. That's basically 
why I split the patches into two groups. 

The first group (with comes first) does just the conversion
and renames from txt to rst, adding a :orphan: to the stuff that was
just converted.

On this series, those are patches 1 to 11. I was already expecting
some heat on patch 1.

The next group of patches do the renaming part. Those are the ones that
actually took me a lot more time, as I needed to quickly read several docs
in order to understand what's happening, before proposing a change.

That's also the group of patches were I expect more active comments,
as there are several cases where this is not obvious.

Yet, from what I saw, there are some documents that sounds easy to
move, like Documentation/laptops, with (except if I missed something)
clearly belongs to admin-guide.

Applying the second patch series and patches 2 to 11 from this third
series is, IMHO, a good thing to do.

-

IMO, patches 1 and 12 are important, as, after those patches, the
/Documentation dir becomes a lot cleaner:

	$ ls -F Documentation/
	ABI/              fb/              locking/        s390/
	accounting/       features/        logo.gif        scheduler/
	acpi/             filesystems/     logo.txt        scsi/
	admin-guide/      firmware_class/  m68k/           security/
	arm/              firmware-guide/  maintainer/     sh/
	arm64/            fpga/            Makefile        sound/
	auxdisplay/       gpio/            media/          sparc/
	block/            gpu/             mic/            sphinx/
	bpf/              hid/             mips/           sphinx-static/
	cdrom/            hwmon/           misc-devices/   spi/
	Changes@          i2c/             Module.symvers  SubmittingPatches
	CodingStyle       ia64/            netlabel/       target/
	conf.py           ide/             networking/     timers/
	core-api/         iio/             nios2/          trace/
	cpu-freq/         index.rst        openrisc/       translations/
	crypto/           infiniband/      output/         usb/
	devicetree/       input/           packing.txt     userspace-api/
	dev-tools/        ioctl/           parisc/         virtual/
	DocBook/          IPMB.txt         PCI/            vm/
	doc-guide/        isdn/            pcmcia/         w1/
	docutils.conf     kbuild/          power/          watchdog/
	dontdiff          Kconfig          powerpc/        wimax/
	driver-api/       kernel-hacking/  process/        x86/
	EDID/             leds/            RCU/            xtensa/
	fault-injection/  livepatch/       riscv/

Being easy to identify when someone tries to add a new text file there
without thinking on where it would fit[1], and to reorganize the
directory tree in a way that it will fit our needs.

[1] Btw, there are some two files at linux-next, incrementally
    increasing the Documentation/ mess:

	   IPMB.txt and packing.txt.

   Added on those commits:

	commit 51bd6f291583684f495ea498984dfc22049d7fd2
	Author: Asmaa Mnebhi <Asmaa@mellanox.com>
	Date:   Mon Jun 10 14:57:02 2019 -0400

	    Add support for IPMB driver

	commit 554aae35007e49f533d3d10e788295f7141725bc
	Author: Vladimir Oltean <olteanv@gmail.com>
	Date:   Thu May 2 23:23:29 2019 +0300

	    lib: Add support for generic packing operations

   We'll never finish organizing documents while people don't stop
   adding new files to Documentation/ directory.

Thanks,
Mauro