In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages]

[Kashyap Chamarthy <kchamart@redhat.com>]

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