lkml.org 
[lkml]   [2019]   [Apr]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst
Em Tue, 23 Apr 2019 10:54:15 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 23 Apr 2019 15:52:26 +0100
> David Howells <dhowells@redhat.com> 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

\
 
 \ /
  Last update: 2019-04-23 22:27    [W:0.123 / U:0.108 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site