Small improvements to the intro of the reference section.

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.
 Reference section: Reporting issues to the kernel maintainers
 =============================================================
 
-The detailed guides above outline all the major steps in brief fashion, which
-should be enough for most people. But sometimes there are situations where even
-experienced users might wonder how to actually do one of those steps. That's
-what this section is for, as it will provide a lot more details on each of the
-above steps. Consider this as reference documentation: it's possible to read it
-from top to bottom. But it's mainly meant to skim over and a place to look up
-details how to actually perform those steps.
-
-A few words of general advice before digging into the details:
-
- * The Linux kernel developers are well aware this process is complicated and
-   demands more than other FLOSS projects. We'd love to make it simpler. But
-   that would require work in various places as well as some infrastructure,
-   which would need constant maintenance; nobody has stepped up to do that
-   work, so that's just how things are for now.
-
- * A warranty or support contract with some vendor doesn't entitle you to
-   request fixes from developers in the upstream Linux kernel community: such
-   contracts are completely outside the scope of the Linux kernel, its
-   development community, and this document. That's why you can't demand
-   anything such a contract guarantees in this context, not even if the
-   developer handling the issue works for the vendor in question. If you want
-   to claim your rights, use the vendor's support channel instead. When doing
-   so, you might want to mention you'd like to see the issue fixed in the
-   upstream Linux kernel; motivate them by saying it's the only way to ensure
-   the fix in the end will get incorporated in all Linux distributions.
-
- * If you never reported an issue to a FLOSS project before you should consider
-   reading `How to Report Bugs Effectively
-   <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_, `How To Ask
-   Questions The Smart Way
-   <http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to ask good
-   questions <https://jvns.ca/blog/good-questions/>`_.
-
-With that off the table, find below the details on how to properly report
-issues to the Linux kernel developers.
+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.
+
+* A warranty or support contract with some vendor doesn't entitle you to
+  request fixes from the upstream Linux developers: Such contracts are
+  completely outside the scope of the upstream Linux kernel, its development
+  community, and this document -- even if those handling the issue work for the
+  vendor who issued the contract. If you want to claim your rights, use the
+  vendor's support channel.
+
+* If you never reported an issue to a FLOSS project before, consider skimming
+  guides like `How to ask good questions
+  <https://jvns.ca/blog/good-questions/>`_, `How To Ask Questions The Smart Way
+  <http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to Report
+  Bugs Effectively <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_,.
+
+With that off the table, find below details for the steps from the detailed
+guide on reporting issues to the Linux kernel developers.
 
 
 Make sure you're using the upstream Linux kernel
-- 
2.51.0

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.

> 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".  But a lot of
the complexity, as reflected in this guide, has to do with properly
gathering the information that is needed to have a hope at tracking a
problem down.  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.

Otherwise seems OK.

Thanks,

jon

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