[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch, Trivial
From: |
Kashyap Chamarthy |
Subject: |
In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages] |
Date: |
Tue, 5 Oct 2021 18:03:58 +0200 |
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
- 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 <=
- Re: In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages], Philippe Mathieu-Daudé, 2021/10/05