[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch, Tr
From: |
Philippe Mathieu-Daudé |
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 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.1.0 |
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
>
- Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages, Stefan Hajnoczi, 2021/10/05
- Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages, Kashyap Chamarthy, 2021/10/05
- Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages, Stefan Hajnoczi, 2021/10/05
- Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages, Kashyap Chamarthy, 2021/10/05
- Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages, Philippe Mathieu-Daudé, 2021/10/05
- Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages, Daniel P . Berrangé, 2021/10/05
- In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages], Kashyap Chamarthy, 2021/10/05
- Re: In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages],
Philippe Mathieu-Daudé <=