Re: [RFC PATCH v2 00/26] Make reporting-bugs easier to grasp and yet more detailed & helpful

[Jonathan Corbet]

On Fri, 20 Nov 2020 11:46:07 +0100
Thorsten Leemhuis <linux@xxxxxxxxxxxxx> wrote:

> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
> > On Sun, 15 Nov 2020 11:13:52 +0100
> > Thorsten Leemhuis <linux@xxxxxxxxxxxxx> wrote:  
> 
> >   - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
> >     (or some suitable name).  I do wonder if it should also move to the
> >     process manual as part of this; not only admins will report bugs.  
> 
> After a night's sleep and Randy's comment I for now settled on
> Documentation/admin-guide/reporting-issues.rst

Keeping it in the admin guide is OK.  Not sure about the name, though; if
you're really dead set against bugs, maybe reporting-problems.rst?

> >   - Add a comment at the top saying it's a proposed replacement and
> >     soliciting comments.  [...]  
> Struggled a bit to find the right words, but I think this should work:
> 
> ```
> .. important::
> 
>     This document is being prepared to replace 
> Documentation/admin-guide/reporting-bugs.rst. The main work is done and 
> you are already free to follow its instructions when reporting issues to 
> the Linux kernel developers. But keep in mind, below text still needs a 
> few finishing touches and review. It was merged to the Linux kernel 
> sources at this stage to make this process easier and increase the 
> text's visibility.
> 
>     Any improvements for the text or other feedback is thus very much 
> welcome. Please send it to 'Thorsten Leemhuis <linux@xxxxxxxxxxxxx>' and 
> 'Jonathan Corbet <corbet@xxxxxxx>', ideally with 'Linux kernel mailing 
> list (LKML) <linux-kernel@xxxxxxxxxxxxxxx>' and the 'Linux Kernel 
> Documentation List <linux-doc@xxxxxxxxxxxxxxx>' in CC.
> 
>     Areas in the text that still need work or discussion contain a hint 
> like this which point out the remaining issues; all of them start with 
> the word "FIXME" to make them easy to find.
> ```

Seems OK.

> >   - In a separate patch you could add a comment to the existing document
> >     pointing to the new one as the true source of wisdom.  
> 
> This is what I plan to add:
> 
> ```
> .. note::
> 
>     Instead of reading below text consider reading this document 
> instead: Documentation/admin-guide/reporting-issues.rst. It's intended 
> to replace below text in the near future, as it's easier to grasp and 
> more straight forward; it also provides way more details and more 
> accurately describes the steps currently needed when reporting bugs to 
> the Linux developers.
> ```

I'd be a bit more straightforward:

	This document is obsolete, and will be replaced by
	Documentation/admin-guide/$NAME in the near future.

Not sure that more is really needed?

jon