Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments

[Akira Yokosawa <akiyks@gmail.com>]

On Fri, 10 Jun 2022 18:08:43 +0200,
Miguel Ojeda wrote:
> On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
> <jani.nikula@linux.intel.com> wrote:
Thank Jani and Miguel for chiming in!
As this is a RFC patch, I'm glad to have nice comments from both of you.

>>
>> When I wrote the original guidelines, it was my subjective decision to
>> steer towards using the same title adornment styles and ordering across
>> the kernel documentation. I intentionally left out all the
>> reStructuredText details about this, because the definitive
>> documentation is the reStructuredText documentation we can refer to.
>>
>> While the "Nth level title" is a more precise description, I'm not sure
>> it's actually helpful without describing how these levels should map to
>> kernel documentation structure. (Not saying the original did that
>> either, but then there wasn't much structure to speak of.)
I agree that we need to cover in doc-guide the way the kernel documentation
is organized and managed.  Total lack of such documentation is kind of
surprising to me.

> 
> To give a bit of context: this patch followed from a question I asked
> to Jonathan and Akira privately. Currently it is hard to tell the
> "nesting level", and even worse, existing files are not consistent and
> checking is not automated. Therefore, an easy way to handle this is to
> request to follow the same pattern regardless of nesting across the
> tree.
> 
>> Improving the documentation on documentation is great, but I think it's
>> a bad sign when length of the notes and warnings on something far exceed
>> the length of the thing being documented. The bulk of the text should be
>> helpful enough for people to DTRT, while leaving out exhaustive
>> descriptions of all the details that should just be references to
>> reStructuredText documentation.

So, I was not aware of such a hidden rule on what should _not_ be in
doc-guide.  :-)
In my opinion, RST documentation is not easy to follow especially for
new contributors, and putting some useful tips somewhere in doc-guide
would improve situation.

I agree with you that those notes and warning don't belong to guidelines.

Maybe add a section collecting RST tips and tricks mainly consisting
of pointers to RST and docutils documentation.

> 
> Perhaps we can move the rationale to the commit message, and keep only
> the current rules in the document. What about something like:
> 
> """
> Please stick to this relative order of adornments within each file
> (i.e. regardless of nesting level across the kernel tree):
> 
>     1. ``=`` with overline.
>     2. ``=``.
>     3. ``-``.
>     4. ``~``.
> 
> For instance::
> 
>     =====
>     First
>     =====
> 
>     Second
>     ======
> 
>     Third
>     -----
> 
>     Fourth
>     ~~~~~~
> """

I'm more inclined to keep "level"s in the example.
Without them, a new contributor might be confused to use those
adornments exactly in that order, for example:

    ==============
    Document title
    ==============

    Chapter A
    =========

    Section A.1
    -----------

    Section A.2
    ~~~~~~~~~~~

    Section A.3
    ???????????

Unlikely, but possible...

Anyway, I'll post a v2 for your further comments.
Might take a while.

        Thanks, Akira
> 
> Cheers,
> Miguel