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

From: "Philippe Mathieu-Daudé" <philmd@redhat.com>
To: "Kashyap Chamarthy" <kchamart@redhat.com>,
	"Daniel P. Berrangé" <berrange@redhat.com>
Cc: Peter Maydell <peter.maydell@linaro.org>,
	Thomas Huth <thuth@redhat.com>, John Snow <jsnow@redhat.com>,
	Michael Tokarev <mjt@tls.msk.ru>,
	Laurent Vivier <laurent@vivier.eu>,
	qemu-devel@nongnu.org, Stefan Hajnoczi <stefanha@redhat.com>,
	Paolo Bonzini <pbonzini@redhat.com>,
	Eric Blake <eblake@redhat.com>
Subject: Re: In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch,  TrivialPatches, and SpellCheck wiki pages]
Date: Tue, 5 Oct 2021 18:06:29 +0200	[thread overview]
Message-ID: <d5e44a59-13aa-6bae-3511-2f5b135fbef8@redhat.com> (raw)
In-Reply-To: <YVx3bqvVny2wdTEh@paraplu>

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
>