On 10/5/21 18:03, Kashyap Chamarthy wrote: > 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.
This example is very convincing :) > (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 >
