Re: [PATCH 00/10] docs/migration: Reorganize migration documentations

[Peter Xu <peterx@redhat.com>]

On Tue, Jan 09, 2024 at 02:21:26PM +0100, Cédric Le Goater wrote:
> 
> > A few things I'd like to mention alongside, because it's documentation
> > relevant too, and I'd like to collect if there's any comment.
> > 
> > I just mostly rewrote two wiki pages completely:
> > 
> >    https://wiki.qemu.org/ToDo/LiveMigration
> >    https://wiki.qemu.org/Features/Migration>
> > I merged all the TODO items from Features/Migration into the ToDo page,
> > while kept the 2nd page mostly clean, just to route to other places.
> > 
> > I had a plan to make:
> > 
> >    https://qemu.org/docs/master
> > 
> > The solo place for migration documentations (aka, QEMU repo the source of
> > truth for migration docs, as it's peroidically built there), making all the
> > rest places pointing to that, as I already did in the wiki page.  While I
> > kept all the TODOs on the wiki page (not Features/Migration, but
> > ToDo/LiveMigration).> Fabiano / anyone: feel free to add / update /
> > correct any entries there
> > where applicable.  Also if there's any thoughts on above feel free to let
> > me know too.
> 
> The Wiki has some limited value, the changelog for instance, but the rest
> is a bag of orphan and obsolete pages doomed to bit-rot since it is slowly
> being replaced by the in-tree documentation.
> 
> The info in the Features/Migration page is redundant with what we have
> in-tree, a part from the CREDITS. The TODO list could be some file under :
> 
> 	https://qemu.org/docs/master/devel/migration
> 
> It would be easier to find and it would keep the Wiki to a strict minimum.

Thanks for the suggestions.  I agree that we should minimize the wiki use,
especially on docs.  It'll be nice we use a solo source of truth for the
docs, always accessable via qemu.org/docs, and also makes it easier for us
to ask for docs altogether as patches when new features are merged.

I see that most of the ToDos for the other part of qemus still use the wiki
page, even though they're indeed mostly outdated just like the migration
ToDo before I updated it.

IMHO one thing that the wiki services well for ToDo is that it allows easy
& frequent updates on the projects, without the need to require a review
process like most of the patches being posted on the list.  The wiki page
still maintains a diff, and IMHO that may not even be required, as a
history record of a ToDo list may not help much in most cases.

The other issue regarding ToDo is that, some of the ToDo idea (or when
someone frequently updates with details on a project of an ongoing item)
may not be mature enough to be mentioned in an official documents. So even
if some can be considered to be put together with the qemu repo, there may
always be some that may not be suitable, then we will still need some place
for those.  I still don't know what's the ideal way to do this.

Thanks,

-- 
Peter Xu