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
