Message-ID: <87o72py8z4.fsf@trenco.lwn.net>
Date: Fri, 08 Nov 2024 09:40:47 -0700
From: Jonathan Corbet <corbet@....net>
To: Sebastian Fricke <sebastian.fricke@...labora.com>
Cc: bagasdotme@...il.com, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org, linux-media@...r.kernel.org,
 laurent.pinchart@...asonboard.com, hverkuil-cisco@...all.nl,
 mauro.chehab@...ux.intel.com, kernel@...labora.com,
 bob.beckett@...labora.com, nicolas.dufresne@...labora.com
Subject: Re: [PATCH 1/2] docs: Add guides section for debugging

Sebastian Fricke <sebastian.fricke@...labora.com> writes:

> Hey Jonathan,
>
> On 07.11.2024 13:35, Jonathan Corbet wrote:
>>Please, let's not add this to the top-level page.  I've been through a
>>multi-year struggle trying to trim that page down to the point where it
>>is possible to actually find something of interest there.  Everybody
>>wants their stuff up front, but please link this from the process guide
>>instead.
>
> Hmmm ... we are talking about a page for newbies here, when it is under
> process the person will have to figure out first that one has to click
> on All development-process docs and then find that document under the
> abundance of others. Could we atleast generate a top level page called
> Beginner intro or something similar, where you are guided through the
> documentation tree from the perspective of a beginner?

By the time somebody needs this document, they should be at least
wrist-deep in kernel development and should be able to find it.

Now, as per the discussion with Randy, if we decide we want to separate
"how to work on kernel code" from "how to work with the kernel
community", we can do that.  We're talking about a bigger organizational
issue at this point, though.

Meanwhile, more introductory documentation is always a good thing :)

>>When referencing the function, say printk() - that's the convention we
>>use.
>
> Ah even in the title? Can do. (Even though it makes the titles look less
> uniform..)

That would be my preference, yes.

>>That is anything but full documentation of lockdep; it's really only
>>about RCU.  I wish (hint :) that we had proper documentation for lockdep
>>that we could link here.  For the purposes of a reader who needs this
>>level of guide, though, linking deep into RCU is not likely to be
>>helpful.
>
> Yep I struggled finiding something useful for this topic in the docs.
> I'd say I skip adding a link for now and we can create another MR later
> to add a proper documentation + link in the documentation.

Sounds like a good plan to me.

>>> diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst
>>> new file mode 100644
>>> index 000000000000..c200ede7c955
>>> --- /dev/null
>>> +++ b/Documentation/process/debugging/index.rst
>>> @@ -0,0 +1,21 @@
>>> +.. SPDX-License-Identifier: GPL-2.0
>>> +
>>> +============================================
>>> +Debugging advice for Linux Kernel developers
>>> +============================================
>>> +
>>
>>This file needs an introductory paragraph (at least) saying what it is
>>about.  A simple directory listing is not hugely useful.
>>
>>An alternative might be to turn your "general advice" document into the
>>index.rst file.
>
> Well that is what I had in the previous iteration and Bagas Sanjaya told me:
>>Please split general debugging advice into its own doc (e.g. at
>>general-advice.rst). Most other docs have index.rst only for toctree
>>listing.
>
> So, shall I revert that or should I add a intro sentence to the index
> file?

Bagas is fond of giving bad but authoritative-sounding advice to
documentation contributors despite repeated requests to stop.
Unfortunately, I don't have the time to chase him around all the time
and set things straight.

My preference would be to go back to what you had, but if you prefer to
just add an intro paragraph at this point we can certainly live with it. 

>>> +  $ alias ddcmd='echo $* > /proc/dynamic_debug/control'
>>> +  $ ddcmd '-p; file v4l2-h264.c +p'
>>
>>It seems to me that the alias just obfuscates things, why bother?
>
> Well because the Linux Kernel documentation suggests that :P
> https://docs.kernel.org/admin-guide/dynamic-debug-howto.html#controlling-dynamic-debug-behaviour
>
> If you don't like that, then I think I should send a MR for that file as
> well.

Up to you, this is just something that caught my eye as I was going by. 

>>> +  To analyse the crash dump please use `Kdump` & `Kexec`.
>>
>>Those will not *analyze* a crash dump.
>
> Well yes they will capture the crash dump, which can then be used to
> analyse the crash. Maybe a better wording is:
>
> To capture the crash dump please use `Kdump` & `Kexec`. Below you can
> find some advice for analysing the data.
>
> better?

Yes, thanks.

jon

Powered by blists - more mailing lists