Re: [PATCH] doc: Explain light-handed markup preference a bit better

[Jonathan Corbet <corbet@lwn.net>]

On Wed,  7 Dec 2016 16:42:58 +0100
Daniel Vetter <daniel.vetter@ffwll.ch> wrote:

> We already had a super-short blurb, but worth extending it I think:
> We're still pretty far away from anything like a consensus, but
> there's clearly a lot of people who prefer an as-light as possible
> approach to converting existing .txt files to .rst. Make sure this is
> properly taken into account and clear.
> 
> Motivated by discussions with Peter and Christoph and others.

I do think we should put something in to guide people in the right
direction.  And yes, it should, itself, be light-handed and minimal.

[...]

>  Documentation/kernel-documentation.rst | 28 ++++++++++++++++++++++++++--
>  1 file changed, 26 insertions(+), 2 deletions(-)

I do, however, also believe that it should apply to relatively recent
docs-next :)

> diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
> index 0dd17069bc0b..5bffe5a418aa 100644
> --- a/Documentation/kernel-documentation.rst
> +++ b/Documentation/kernel-documentation.rst
> @@ -77,9 +77,27 @@ Specific guidelines for the kernel documentation
>  
>  Here are some specific guidelines for the kernel documentation:
>  
> -* Please don't go overboard with reStructuredText markup. Keep it simple.
> +* Please don't go overboard with reStructuredText markup. Keep it simple. A lot
> +  of core kernel developers prefer plain text, with a big emphasis on plain. In
> +  the end if we have pretty generated docs which the subject experts don't
> +  like to edit and keep up-to-date everyone loses.
>  
> -* Please stick to this order of heading adornments:
> +  Be especially considerate when converting existing documentation. There's a
> +  wide scale from annotating every little bit with in-line styles to only
> +  touching up the bare minimum needed to integrate an existing file into the
> +  larger documentation. Please align with the wishes of the maintainer to make
> +  sure that documentations stays useful for everyone.

I think this is about where I figured out why I'm not 100% ready to jump on
this.  What we're doing here is mixing two things: information on how to
write documents, and information on how to convert existing documents.

I'm not really opposed to applying the patch as-is, but I do wonder if what
we really need is a new section aimed specifically at people doing
conversions?  The concerns *are* a bit different, and there's more
information we could put into a conversion section that isn't relevant to
others.  Plus we could remove it some day far in the future when
everything's converted :)

> +* Don't just blindly convert documents, also carefully review them and fix up
> +  any issues in the text itself. Updated docs might trick readers into believing
> +  they're accurately reflecting current best practice, which would be rather
> +  harmful if the text itself is entirely outdated.
> +
> +* When converting existing documents, please try to retain the existing heading
> +  styles as much as possible. Sphinx accept almost anything, as long as it's

accept*s*  (or "will accept")

> +  consistent and headings all start in column 1.
> +
> +  For new documents please stick to this order of heading adornments:
>  
>    1. ``=`` with overline for document title::
>  
> @@ -107,6 +125,12 @@ Here are some specific guidelines for the kernel documentation:
>    the order as encountered."), having the higher levels the same overall makes
>    it easier to follow the documents.
>  
> +* For inserting fixed width text blocks (for code examples, use case
> +  examples, etc.), use ``::`` for anything that doesn't really benefit
> +  from syntax highlighting, especially short snippets. Use
> +  ``.. code-block:: <language>`` for longer code blocks that benefit
> +  from highlighting.
> +

I think we should add a sentence somewhere saying:

  Note that, if the sentence before the block ends with ":", you can simply
  add a second colon rather than putting in a separate "::" line.

I've had to tell a few people that.  It's a tiny detail, but one that does
improve the readability of the resulting documents and reduce the
intrusiveness of conversions.

Thanks,

jon