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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Jul 16, 2021, 17:04 UTC
Message-ID: <60f1bc162a797_ade92086e@natae.notmuch>
In-Reply-To: <nycvar.QRO.7.76.6.2107161732150.59@tvgsbejvaqbjf.bet>

Johannes Schindelin wrote:

Show 13 quoted lines

> On Tue, 13 Jul 2021, Ævar Arnfjörð Bjarmason wrote:
> 
> > [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.

Show 5 quoted lines

> > 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