Received-SPF: pass (google.com: domain of linux-kernel+bounces-118963-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
From: Thorsten Leemhuis <linux@leemhuis.info>
To: Jonathan Corbet <corbet@lwn.net>
Cc: regressions@lists.linux.dev,
	linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org,
	workflows@vger.kernel.org
Subject: [RFC PATCH v1 0/2] docs: reporting-issues: rework while involving the 'verify bugs' text
Date: Tue, 26 Mar 2024 13:21:27 +0100
Message-ID: <cover.1711455295.git.linux@leemhuis.info>
Precedence: bulk
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

This is a RFC with two WIP patches that basically rewrite the detailed
step-by-step guide and the TLDR of
Documentation/admin-guide/reporting-issues.rst. Those two patches cover
all main changes I currently plan to do in those areas of the text, but
the explanations in the reference section are not yet updated to match
the changed step-by-step guide.

I'm nevertheless posting this now as RFC so people get a chance to
express things like "Thorsten, you are crazy, go away and find a hobby"
or "you are on the wrong path, this makes things worse, and would also
create a lot of trouble for translators for a questionable gain".
Getting such feedback now would be good: I'd prefer to not waste time on
updating the reference section if something like the two patches posted
here have no chance to be merged.

That being said: I (obviously) think these changes are worth it, as they
make both the TLDR and the guide easier to follow and fix a few things
that didn't work too well. It also offers users a new fast track to
inquire if a regression is known already. The step-by-step guide
furthermore is now a bit more verbose, so users have to consult the
reference section less -- this felt appropriate, now that the TLDR uses
a step-by-step approach as well that is quite similar.

In the end it looks like a rewrite, even if many things remained
similar. And all in all those changes sadly makes both sections larger:

TLDR:
- before: 374 words, 2332 characters;
- after: 491 words, 3085 characters

Step-by-step guide:
- before: 1058 words, 6279 characters (excluding a section that becomes
  obsolete)
- before: 1332 words, 8048 characters (including a section that becomes
  obsolete)
- after: 1491 words, 9015 characters;

Note, the changes to the reference section should not turn out to be as
extensive as these two patches, as many of the steps in the new detailed
step-by-step guide had equivalents in the older one; many sections in
the reference section will thus only need small changes or maybe none at
all; a few things are also unnecessary now, so the reference section
should get shorter.

To alleviate reviewing and translations, I plan to submit the changes to
the reference section in two steps. The first patch will perform all
changes, but will add newlines before significant changes, which will
wrap at 120 characters or so: both things should make it easier to see
the actual changes with ordinary diff. A second patch then will just
rewrap the text to the usual 80 characters boundary.

Side note: the two patches submitted now could and maybe should be
merged into one, but I decided to keep them separate for now to have
section-specific diffstats.

Thorsten Leemhuis (2):
  docs: reporting-issue: rework the detailed guide
  docs: reporting-issue: rework the TLDR

 .../admin-guide/reporting-issues.rst          | 497 ++++++++++--------
 1 file changed, 273 insertions(+), 224 deletions(-)


base-commit: b8cfda5c9065cd619a97c17da081cbfab3b1e756
-- 
2.44.0