Re: [PATCH v1 02/30] docs: reporting-issues: tweak the reference section intro

[Thorsten Leemhuis <linux@leemhuis.info>]

On 10/27/25 18:27, Jonathan Corbet wrote:
> Thorsten Leemhuis <linux@leemhuis.info> writes:
> 
>> Small improvements to the intro of the reference section.
> 
> That's a bit uninformative ... what is the purpose of these
> improvements?  That information would be especially helpful in a patch
> that simply replaces that section altogether.

Sorry, yes, of course, changes that to

"""
Fine tuning to the intro of the reference section:

 * Call the step-by-step guide what it is.
 * Reorder the links to the guides on bug reporting to first mention the
  most modern one.
 * Many small changes to streamline the text and slightly shorten it
"""

>> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
>> ---
>>  .../admin-guide/reporting-issues.rst          | 67 +++++++++----------
>>  1 file changed, 31 insertions(+), 36 deletions(-)
>>
>> diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
>> index 3bc47afaf85ea0..90b50c27c0d2b6 100644
>> --- a/Documentation/admin-guide/reporting-issues.rst
>> +++ b/Documentation/admin-guide/reporting-issues.rst
>> @@ -244,42 +244,37 @@ The reference section below explains each of these steps in more detail.
> 
> [...]
> 
>> +The step-by-step guide above outlines all the major steps in brief fashion,
>> +which usually covers everything required. But even experienced users will
>> +sometimes wonder how to actually realize some of those steps or why they are
>> +needed; there are also corner cases the guide ignores for readability. That is
>> +what the entries in this reference section are for, which provide additional
>> +information for each of the steps in the detailed guide.
>> +
>> +A few words of general advice:
>> +
>> +* The Linux kernel developers are well aware that reporting bugs to them is
>> +  more complicated and demanding than in other FLOSS projects. Quite a few
>> +  would love to make it simpler. But that would require convincing a lot of
>> +  developers to change their habits; it, furthermore, would require improvements
>> +  on several technical fronts and people that constantly take care of various
>> +  things. Nobody has stepped up to do or fund that work.
> 
> This paragraph ... essentially says "we're making it hard on you because
> kernel developers can't be bothered to work on GitHub".

/me looks puzzled
/me noticed that Jonathan is right
/me looks puzzled in a different way

> I'm not sure this paragraph is needed at all but, if
> you're going to keep it, have it at least reflect that the complexity of
> problem reporting has a lot to do with the complexity of the problem
> domain rather than developers who are stuck in their habits.

Considered dropping it, but in the end decided that I think it's wort it
and changed it to:

* The Linux developers are well aware that reporting bugs to them is
more complicated and demanding than in other FLOSS projects. Some of it
is because the kernel is different, among others due to its mail-driven
development process and because it consists mostly of drivers. Some of
it is because improving things would require work in several technical
areas and people triaging bugs –– and nobody has stepped up to do or
fund that work.

Ciao, Thorsten