From:   Jonathan Corbet <corbet@lwn.net>
To:     Bagas Sanjaya <bagasdotme@gmail.com>,
        Shuah Khan <skhan@linuxfoundation.org>
Cc:     sshefali021@gmail.com, kstewart@linuxfoundation.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v3] docs: add workload-tracing document to admin-guide
In-Reply-To: <Y9nkqhAS6EW2Lu8Z@debian.me>
References: <20230131221105.39216-1-skhan@linuxfoundation.org>
 <Y9nkqhAS6EW2Lu8Z@debian.me>
Date:   Wed, 01 Feb 2023 16:41:41 -0700
Message-ID: <875yclx8ay.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On Tue, Jan 31, 2023 at 03:11:05PM -0700, Shuah Khan wrote:
>> Add a new section to the admin-guide with information of interest to
>> application developers and system integrators doing analysis of the
>> Linux kernel for safety critical applications.
>> 
>> This section will contain documents supporting analysis of kernel
>> interactions with applications, and key kernel subsystems expectations.
>> 
>> Add a new workload-tracing document to this new section.
>> 
>> Signed-off-by: Shefali Sharma <sshefali021@gmail.com>
>> Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>
>> ---
>> Changes since v2: Addressed review comments on v2
>
> I think you haven't addressed my comments there [1], so I have to
> write the improv:

Bagas, could you *please* stop this?

> diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst
> index 5fad64b4ebd66f..ac60ff9dec8f0e 100644
> --- a/Documentation/admin-guide/workload-tracing.rst
> +++ b/Documentation/admin-guide/workload-tracing.rst
> @@ -27,10 +27,10 @@ Methodology
>  ===========
>  
>  `strace <https://man7.org/linux/man-pages/man1/strace.1.html>`_ is a
> -diagnostic, instructional, and debugging tool and can be used to discover
> -the system resources in use by a workload. Once we discover and understand
> -the workload needs, we can focus on them to avoid regressions and use it
> -to evaluate safety considerations. We use strace tool to trace workloads.
> +diagnostic, instructional, and debugging tool and can be used to
> +discover the system resources in use by a workload by tracing it. Once
> +we discover and understand the workload needs, we can focus on them to
> +avoid regressions and use it to evaluate safety considerations.

Do you realize how long it takes to look at this kind of stuff to decide
whether it is an "improv" or not?  In this case, it decidedly is not,
but somebody has to spend a bunch of time to try to figure out what you
were doing.

>  This method of tracing using strace tells us the system calls invoked by
>  the workload and doesn't include all the system calls that can be invoked
> @@ -43,7 +43,7 @@ outlined here will trace and find all possible code paths. The completeness
>  of the system usage information depends on the completeness of coverage of a
>  workload.
>  
> -The goal is tracing a workload on a system running a default kernel without
> +The goal is to trace workloads on a system running a default kernel without
>  requiring custom kernel installs.

Why do you think that these sorts of trivial changes are worth the
trouble?

I have asked you numerous times to please stop harassing our
contributors.  I am asking yet again.  We have no need for a
self-appointed officer to police documentation patches; you are simply
adding impedance to a process that people already find difficult to
navigate.

If you want to help the kernel project, we welcome you, but you need to
find a way to actually *help*.  As I have asked before, please stop
worrying about what others are doing and focus on making positive
contributions yourself.

Thank you.

jon