Merge Request workflow for docs updates (was Re: RFC: Merge Request documenting a contributor-initiated orphaning process in the Developers Reference)

"Jonathan Dowland" <[email protected]> Wed, 01 Jul 2026 09:40:06 +0100

Newsgroups	gmane.linux.debian.devel.general
Message-ID	<[email protected]>

(This was motivated by Andreas's mail in <[email protected]> but 
is not directly related to that piece of work.)

What are my fellow developer's opinions on the suitability of the Merge 
Request workflow for documentation updates?

I like the idea in theory, but my experiences so far (most recently with 
Raphael's DEP improvement work) is that it very quickly breaks down. For 
software, quite often the feedback you receive on a PR can be resolved 
in a very local manner: i.e., you can fix a typo, add a comment, adjust 
the approach used within a function, and the result is a very localised 
change, and this works fine with MR feedback.

With documentation, often the kind of changes that are worth doing 
involve cascading changes all over the place. Such as: use this 
particular term consistently; or restructure the order of how concepts 
are introduced; or remove this section and all references to it. It's 
also easier to express relatively trivial improvements (typos, grammar, 
punctuation) with MR comments, than it is more fundamental and important 
changes (don't do this at all, or do this first, etc). The latter 
suggestions are drowned out by the former.

Fundamentally I think documentation is sufficiently different to 
software that a different approach is needed for collaborative editing. 
In my experience the best (but by no means perfect) systems have been 
wiki-like.


-- 
⢀⣴⠾⠻⢶⣦⠀
⣾⠁⢠⠒⠀⣿⡁ Jonathan Dowland
⢿⡄⠘⠷⠚⠋⠀ https://jmtd.net
⠈⠳⣄⠀⠀⠀⠀

signature.asc (application/pgp-signature, 833 B)