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] [day] [month] [year] [list]

Message-ID: <20191101140121.3d0575dd@cakuba.netronome.com>
Date:   Fri, 1 Nov 2019 14:01:21 -0700
From:   Jakub Kicinski <jakub.kicinski@...ronome.com>
To:     Jonathan Corbet <corbet@....net>
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 Wed, 30 Oct 2019 09:02:52 -0700, Jakub Kicinski wrote:
> On Wed, 30 Oct 2019 02:44:30 -0600, Jonathan Corbet wrote:
> > On Tue, 29 Oct 2019 10:12:15 -0700
> > Jakub Kicinski <jakub.kicinski@...ronome.com> wrote:  
> > > -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?  
> 
> I agree that this is suboptimal. I couldn't come up with a better way
> of handling this. I think consistently formatting all questions in one
> way and answers in another make the document far easier to interpret.
> I had hard time follow the current formatting:
> 
> https://www.kernel.org/doc/html/latest/networking/netdev-FAQ.html#q-i-have-created-a-network-patch-and-i-think-it-should-be-backported-to-stable
> 
> Is there a more appropriate form of emphasis we could use here? Even
> if we add independent headings questions should remain emphasised
> _somehow_ I reckon..

I poked a little bit more, adding first level headings make the
questions smaller which is nice. But they are still headings.
Then I watched your presentation from Kernel Recipes which reminded 
me of the plan to add some per subsystem process files. Which would
obsolete this doc :) Since that's a hornet's nest I don't wish 
to poke I will leave this work for a braver soul :)