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 [thread overview]
Message-ID: <cover.1711455295.git.linux@leemhuis.info> (raw)
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
next reply other threads:[~2024-03-26 12:21 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-26 12:21 Thorsten Leemhuis [this message]
2024-03-26 12:21 ` [RFC PATCH v1 1/2] docs: reporting-issue: rework the detailed guide Thorsten Leemhuis
2024-04-10 20:58 ` Jonathan Corbet
2024-03-26 12:21 ` [RFC PATCH v1 2/2] docs: reporting-issue: rework the TLDR Thorsten Leemhuis
2024-04-10 21:00 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=cover.1711455295.git.linux@leemhuis.info \
--to=linux@leemhuis.info \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=regressions@lists.linux.dev \
--cc=workflows@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.