Re: [PATCH 2/2] docs: media: Debugging guide for the media subsystem

[Jonathan Corbet <corbet@lwn.net>]

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

> Hey Jonathan,
>
> On 08.11.2024 11:12, Sebastian Fricke wrote:
>>Hey Jon,
>>
>>On 07.11.2024 13:40, Jonathan Corbet wrote:
>>>Sebastian Fricke <sebastian.fricke@collabora.com> writes:
>>>
>>>>Provide a guide for developers on how to debug code with a focus on the
>>>>media subsystem. This document aims to provide a rough overview over the
>>>>possibilities and a rational to help choosing the right tool for the
>>>>given circumstances.
>>>>
>>>>Signed-off-by: Sebastian Fricke <sebastian.fricke@collabora.com>
>>>>---
>>>> Documentation/process/debugging/index.rst          |   1 +
>>>> .../debugging/media_specific_debugging_guide.rst   | 178 +++++++++++++++++++++
>>>> 2 files changed, 179 insertions(+)
>>>
>>>Mostly overall comments here
>>>
>>>- much of what's here seems redundant with your other new documents; you
>>> seem to be going over the same list of tools?  Why not just talk about
>>> the ones that are unique to the media subsystem?
>>
>>I choosed the minimum duplication path because of the perspective that I
>>envisioned of the reader.
>>The reader reads that there is a debugging guide for the media
>>subsystem, which to my ears sounds like:
>>"Everything you need to know to get started debugging in this subsystem,
>>with recommendations for useful tools"
>>and not
>>"Some specific media bits that expect you to have read every other
>>debugging documentation and judge yourself which of these tools might be
>>useful for your debugging".
>>
>>I look at that specifically from a perspective that the general
>>debugging guides are probably going to be extended in the future with
>>more general debugging tools which might not be as useful for the media
>>subsystem.
>
> @Jon: Does that sound reasonable to you? Or should I rework the page? I
> think this is especially interesting for the audio debugging guide as
> well, because this determines how subsystem specific guides should be
> formatted.

I would suggest trying to minimize the amount of duplicated material;
more duplication is more work to maintain and inevitably goes out of
sync.  That said, I don't want to send you around in too many circles on
this; and would not try to require such a change.  It's a suggestion;
get the docs to where you're happy with them and we'll be glad to take
them.

Thanks,

jon