From:   Jonathan Corbet <corbet@lwn.net>
To:     Thorsten Leemhuis <linux@leemhuis.info>
Cc:     Randy Dunlap <rdunlap@infradead.org>,
        Lukas Bulwahn <lukas.bulwahn@gmail.com>,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        regressions@lists.linux.dev, Greg KH <gregkh@linuxfoundation.org>,
        Jani Nikula <jani.nikula@linux.intel.com>
Subject: Re: [PATCH v2] docs: describe how to quickly build a trimmed kernel
In-Reply-To: <8cfcf069d48c1b8d7b83aafe0132f8dad0f1d0ea.1676400947.git.linux@leemhuis.info>
References: <8cfcf069d48c1b8d7b83aafe0132f8dad0f1d0ea.1676400947.git.linux@leemhuis.info>
Date:   Thu, 16 Feb 2023 17:30:24 -0700
Message-ID: <873575gmlb.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Thorsten Leemhuis <linux@leemhuis.info> writes:

> Add a text explaining how to quickly build a kernel, as that's something
> users will often have to do when they want to report an issue or test
> proposed fixes. This is a huge and frightening task for quite a few
> users these days, as many rely on pre-compiled kernels and have never
> built their own. They find help on quite a few websites explaining the
> process in various ways, but those howtos often omit important details
> or make things too hard for the 'quickly build just for testing' case
> that 'localmodconfig' is really useful for. Hence give users something
> at hand to guide them, as that makes it easier for them to help with
> testing, debugging, and fixing the kernel.
>
> To keep the complexity at bay, the document explicitly focuses on how to
> compile the kernel on commodity distributions running on commodity
> hardware. People that deal with less common distributions or hardware
> will often know their way around already anyway.

So this seems generally good though - as is my usual style - if it were
mine I'd be trying to find a way to make it significantly shorter.

I could certainly bikeshed a lot of things - I'm not convinced about the
whole shallow-clone business, for example - but I'll try to restrain
myself.

> The document heavily uses anchors and links to them, which makes things
> slightly harder to read in the source form. But the intended target
> audience is way more likely to read rendered versions of this text on
> pages like docs.kernel.org anyway -- and there those anchors and links
> allow easy jumps to the reference section and back, which makes the
> document a lot easier to work with for the intended target audience.

I do wonder if all that back-and-forth actually makes things easier, and
it definitely impedes use of the RST file.  I recognize that you're
trying to do something a bit different here, though, and don't want to
get in the way of the experiment.  Given the purpose, though, I do have
a couple of little thoughts:

- Somewhere at the top of the RST file should be a prominent link to the
  rendered version, presumably on kernel.org.  It could perhaps be in an
  RST comment that doesn't show up in the rendered version, saying
  "perhaps you really want to read this ----> over there".

- Eventually we should probably make the link to this document more
  prominent on the front page - once we've figured out what we're doing
  there :)

Anyway, those quibbles aside, I think we should probably just apply this
after the merge window.

Thanks,

jon