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

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@netronome.com>
Reviewed-by: Simon Horman <simon.horman@netronome.com>
---
 Documentation/networking/netdev-FAQ.rst | 35 +++++++++----------------
 1 file changed, 13 insertions(+), 22 deletions(-)

On Tue, 29 Oct 2019 10:12:15 -0700
Jakub Kicinski <jakub.kicinski@netronome.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@netronome.com>
> Reviewed-by: Simon Horman <simon.horman@netronome.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@vger.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@vger.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

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@netronome.com> wrote:
> > -Q: I see a network patch and I think it should be backported to stable.
> > ------------------------------------------------------------------------
> > -Q: Should I request it via stable@vger.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@vger.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..

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@netronome.com> wrote:  
> > > -Q: I see a network patch and I think it should be backported to stable.
> > > ------------------------------------------------------------------------
> > > -Q: Should I request it via stable@vger.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@vger.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 :)