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

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

[Jakub Kicinski]

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(-)

diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst
index 642fa963be3c..633d558743b2 100644
--- a/Documentation/networking/netdev-FAQ.rst
+++ b/Documentation/networking/netdev-FAQ.rst
@@ -82,7 +82,7 @@ focus for ``net`` is on stabilization and bug fixes.
 Finally, the vX.Y gets released, and the whole cycle starts over.
 
 Q: So where are we now in this cycle?
-
+-------------------------------------
 Load the mainline (Linus) page here:
 
   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
@@ -105,9 +105,8 @@ in the above is just the subject text of the outgoing e-mail, and you
 can manually change it yourself with whatever MUA you are comfortable
 with.
 
-Q: I sent a patch and I'm wondering what happened to it?
---------------------------------------------------------
-Q: How can I tell whether it got merged?
+Q: I sent a patch and I'm wondering what happened to it? How can I tell whether it got merged?
+----------------------------------------------------------------------------------------------
 A: Start by looking at the main patchworks queue for netdev:
 
   http://patchwork.ozlabs.org/project/netdev/list/
@@ -122,10 +121,8 @@ A: Generally speaking, the patches get triaged quickly (in less than
 patch is a good way to ensure your patch is ignored or pushed to the
 bottom of the priority list.
 
-Q: I submitted multiple versions of the patch series
-----------------------------------------------------
-Q: should I directly update patchwork for the previous versions of these
-patch series?
+Q: I submitted multiple versions of the patch series should I directly update patchwork for the previous versions of these patch series?
+----------------------------------------------------------------------------------------------------------------------------------------
 A: No, please don't interfere with the patch status on patchwork, leave
 it to the maintainer to figure out what is the most recent and current
 version that should be applied. If there is any doubt, the maintainer
@@ -169,10 +166,8 @@ simply clone the repo, and then git grep the mainline commit ID, e.g.
   releases/3.9.8/ipv6-fix-possible-crashes-in-ip6_cork_release.patch
   stable/stable-queue$
 
-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?
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 A: No, not for networking.  Check the stable queues as per above first
 to see if it is already queued.  If not, then send a mail to netdev,
 listing the upstream commit ID and why you think it should be a stable
@@ -190,10 +185,8 @@ mainline, the better the odds that it is an OK candidate for stable.  So
 scrambling to request a commit be added the day after it appears should
 be avoided.
 
-Q: I have created a network patch and I think it should be backported to stable.
---------------------------------------------------------------------------------
-Q: Should I add a Cc: stable@vger.kernel.org like the references in the
-kernel's Documentation/ directory say?
+Q: I have created a network patch and I think it should be backported to stable. Should I add a Cc: stable@vger.kernel.org like the references in the kernel's Documentation/ directory say?
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 A: No.  See above answer.  In short, if you think it really belongs in
 stable, then ensure you write a decent commit log that describes who
 gets impacted by the bug fix and how it manifests itself, and when the
@@ -231,15 +224,13 @@ Q: Is the comment style convention different for the networking content?
    * another line of text
    */
 
-Q: I am working in existing code that has the former comment style and not the latter.
---------------------------------------------------------------------------------------
-Q: Should I submit new code in the former style or the latter?
+Q: I am working in existing code that has the former comment style and not the latter. Should I submit new code in the former style or the latter?
+--------------------------------------------------------------------------------------------------------------------------------------------------
 A: Make it the latter style, so that eventually all code in the domain
 of netdev is of this format.
 
-Q: I found a bug that might have possible security implications or similar.
----------------------------------------------------------------------------
-Q: Should I mail the main netdev maintainer off-list?**
+Q: I found a bug that might have possible security implications or similar. Should I mail the main netdev maintainer off-list?
+------------------------------------------------------------------------------------------------------------------------------
 A: No. The current netdev maintainer has consistently requested that
 people use the mailing lists and not reach out directly.  If you aren't
 OK with that, then perhaps consider mailing security@kernel.org or
-- 
2.23.0

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

[Jonathan Corbet]

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

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

[Jakub Kicinski]

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..

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

[Jakub Kicinski]

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 :)