"Jonathan Dowland" <[email protected]> writes: > (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? >
> > 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. I think this is equally true of code - use this algorithm, rename the variable. > 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. i think most people that comment on documents professionally use some form of "make a comment, and expect the author to address it, including making related changes" which is what you get with MR comments. It's a lot harder than editing code because writing is a lot harder than coding. A wiki is fine if there are multiple authors but you dont actually want that with most documents - you want one voice, not many.
