Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 10:54:15 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:

> On Tue, 23 Apr 2019 15:52:26 +0100
> David Howells <dhowells@xxxxxxxxxx> wrote:
> 
> > There've been some changes that I've particularly objected to, such as
> > removing contents lists from files and replacing them with markup like:
> > 
> > 	.. contents:: :local:
> > 
> > This actually impedes use of the file.  It should not be necessary to build
> > the docs to get that for ordinary use.  
> 
> Usability of the text files versus that of the built docs is occasionally
> something that has to be traded off.  As a general rule, I want the text
> files to remain useful on their own.  There is a lot of value in the
> built docs for a lot of people, but that should not be the only, or even
> the primary, form of access
> 
> Tables of contents are certainly a place where that tradeoff makes itself
> felt.  Doing them by hand ensures that they are always present, but
> requires that people editing the docs also maintain the TOCS - something
> that experience has shown tends not to happen.  That's more of a pain
> than a little bit of markup, and people don't do it.  An automatically
> generated TOC, instead, is always correct and is linkable.
> 
> Few people complain about the biggest impediment to the readability of
> text files, though: the use of kerneldoc comments.  That splits the
> information between the text file and multiple random-seeming locations
> among tends of thousands of source files.  Sometimes the solution here is
> to move all of the documentation into the source, but that tends to
> fragment it and make it harder to find; it's certainly not the right
> place for many kinds of docs.  In general, it's hard to create a coherent
> story that way.
> 
> Suggestions / patches on how to improve things for *all* users of the
> docs are certainly welcome!
> 
> I am, incidentally, toying with the idea of trying to put together a
> documentation microconf at the Linux Plumbers Conference this year.  If
> anybody out there thinks that's a good idea and would like to
> participate, please let me know.

If you add a microconf to LPC, I'm in. 

IMO, we made big advances with documentation, but there's a lot more
to be done. Having a microconf to discuss those things may help us
to bring new ideas about how to keep improving it.

Thanks,
Mauro