netdev - Re: [PATCH net] Documentation: netdev-FAQ: make all questions into headings

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20191030024430.719c73be@lwn.net>
Date:   Wed, 30 Oct 2019 02:44:30 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Jakub Kicinski <jakub.kicinski@...ronome.com>
Cc:     davem@...emloft.net, netdev@...r.kernel.org,
        oss-drivers@...ronome.com, linux-doc@...r.kernel.org,
        Simon Horman <simon.horman@...ronome.com>
Subject: Re: [PATCH net] Documentation: netdev-FAQ: make all questions into
 headings

On Tue, 29 Oct 2019 10:12:15 -0700
Jakub Kicinski <jakub.kicinski@...ronome.com> wrote:

> Make sure all questions are headings. Some questions are
> currently on multiple lines, and the continuation lines
> appear as part of the answer when rendered. One question
> was also missing an underline completely.
> 
> Signed-off-by: Jakub Kicinski <jakub.kicinski@...ronome.com>
> Reviewed-by: Simon Horman <simon.horman@...ronome.com>
> ---
>  Documentation/networking/netdev-FAQ.rst | 35 +++++++++----------------
>  1 file changed, 13 insertions(+), 22 deletions(-)

Thanks for working to improve our documentation!

One quick comment...

[...]

> -Q: I see a network patch and I think it should be backported to stable.
> ------------------------------------------------------------------------
> -Q: Should I request it via stable@...r.kernel.org like the references in
> -the kernel's Documentation/process/stable-kernel-rules.rst file say?
> +Q: I see a network patch and I think it should be backported to stable. Should I request it via stable@...r.kernel.org like the references in the kernel's Documentation/process/stable-kernel-rules.rst file say?
> +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

I don't think that making these massive heading lines actually improves the
experience - for readers of either the plain-text or formatted docs.  If
you really want to create headings, the heading here should be "Stable
backports" or some such with the question appearing below.  But do the
questions really need to be headings?

Thanks,

jon