Re: [PATCH v3 02/34] fsmonitor--daemon: man page

Johannes Schindelin wrote:

On Tue, 13 Jul 2021, Ævar Arnfjörð Bjarmason wrote:

quoted

[snip Ævar's suggestion to populate the manual page incrementally,
interspersed with the commits that finalize implementing the respective
functionality]

I suggested this because I think it's much easier to read patches that
are larger because they incrementally update docs or tests along with
code, than smaller ones that are e.g. "add docs" followed by
incrementally modifying the code.

My experience is the exact opposite of yours: shorter patches are easier
to read.

It depends.

quoted

That's because you can consider those atomically.

No, in a patch series you cannot consider any patch completely atomically.
Just like you don't consider any paragraph in any well-written book out of
context.

But you do not put every sentence in a paragraph.

Sometimes a paragraph can contain a single sentence, or a single word
even. But other times to properly read what is being tried to say you
need a pretty big paragraph.

This all sounds like we're truly falling into the trap of ignoring the
rule that the perfect is the enemy of the good.

Have you established that this is good enough?

-- 
Felipe Contreras