On Tue, Oct 05, 2021 at 04:37:50PM +0100, Daniel P. Berrangé wrote: > On Tue, Oct 05, 2021 at 05:07:06PM +0200, Philippe Mathieu-Daudé wrote:
[...] > > One point Peter raised on IRC is it is easier to update a Wiki page > > than get a patch merged into the repository. IOW we are making things > > harder. > > There are factors to consider beyond ease of contributions. > > Certain information here is documenting a fundamental part of the > QEMU community operation & processes. That ought to have a high > trust level and be subject to review of content changes. I'd say > the SubmitAPatch page falls in this category. > > Other information is essentially random adhoc user written content > that isn't critical to the project. This can live with a low trust > level and little-to-no review. > > IMHO, the wiki should only be considered for the latter type of > content, with any important project content being subject to > review. > > I also feel like docs in git is more likely to be kept upto date > by the regular maintainers, than wikis which can become a bit of > outdated mess. I agree. Here's an example that proves your point: had I written this huge 'live-block-operations.rst'[1] doc as a Wiki, pretty sure it would've been slowly rotting away. Now I see 5 other contributors besides me (including Peter, yourself, and Paolo in this thread) that have patched it ... by virtue of it being in-tree. That makes me even more convinced that having development, interface, and any valuable docs that are in-tree are more well-maintained. (FWIW, I seem to have more motivation to write docs in rST or similar formats that can be iterated over, with in-line reviews like regular patches. I can't claim the same level of motivation to write Wiki pages somehow.) > It is a shame that our normal contribution workflow doesn't make > it easy for simple docs changes to be accepted and merged :-( Yeah; improving that can be nicer. [1] https://qemu.readthedocs.io/en/latest/interop/live-block-operations.html -- /kashyap