linux-kernel - Re: [PATCH v3] docs: describe how to quickly build a trimmed kernel

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <d233a796-1cb8-a9b3-5a50-043dd2f98b3e@leemhuis.info>
Date:   Wed, 15 Mar 2023 10:28:47 +0100
From:   Thorsten Leemhuis <linux@...mhuis.info>
To:     Jonathan Corbet <corbet@....net>
Cc:     Randy Dunlap <rdunlap@...radead.org>,
        Lukas Bulwahn <lukas.bulwahn@...il.com>,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        regressions@...ts.linux.dev
Subject: Re: [PATCH v3] docs: describe how to quickly build a trimmed kernel

On 14.03.23 19:35, Jonathan Corbet wrote:
> Thorsten Leemhuis <linux@...mhuis.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.
> 
> So I think the time has come to apply this.

Sounds good.

>  I did have one final
> thought, though...  In the v2 discussion, you said:
> 
>> Be warned, if it works I might do the same for "reporting issues". ;)
>> But let's first see how this goes (and if we get any feedback to be able
>> to tell if this experiment worked).
> 
> This caused me to wonder if we shouldn't create a new book called
> "tutorials" for this kind of stuff, with an explicit proviso that a more
> web-oriented approach is OK in that section?  Tutorial documentation
> *is* quite different from reference material, but we've really made no
> effort to treat the two differently so far.
> 
> Thoughts?

Hmmm. Thinking about this makes sense, as yes, reference material and
tutorials are different kind of texts.

I'm not against separating, but it currently kinda feels wrong.

Documentation/doc-guide/contributing.rst says that "books" are meant to
"group documentation for specific readers"; creating a new book for
tutorials would work against that, as readers (users and administrators
in this case) then would have to consult two books.

And isn't for example Documentation/process/submitting-patches.rst also
more of a tutorial than reference material (which we also have in the
form of Documentation/process/development-process.rst)? Does that mean
it should be moved? Into the same book or a separate book, as it has a
different target audience? I fear that might quickly get confusing for
readers without any real benefits

Or did I understand the idea of a new book wrong and you meant something
else? Like creating Documentation/admin-guide/tutorials/ and putting the
text there? That might work and would help future authors to get the
right mental model when writing new texts. But I'm not sure that's worth it.

Ciao, Thorsten