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
Description: PGP signature
