Re: [Xen-devel] Migrating key developer docs to xen.git sphinx docs and refreshing them in the process

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Mon, 24 Jun 2019, Julien Grall wrote:
> Hi,
> 
> On 24/06/2019 19:03, Stefano Stabellini wrote:
> > On Mon, 24 Jun 2019, Lars Kurth wrote:
> > I think we all agree by now that maintaining up-to-date docs on the wiki
> > and keeping them in sync with code changes is hard. I see moving things
> > from the wiki to xen.git as a great improvement. We have a few Xen on
> > ARM docs that are worth importing from the wiki:
> > 
> > https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions
> 
> I agree for this but ...
> 
> > 
> > And all the board specific docs linked from it, such as:
> > 
> > https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions/qemu-system-aarch64
> > https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions/FastModels
> > https://wiki.xenproject.org/wiki/HiKey960
> 
> ... I think it is a pretty bad idea to import board specific docs. There 
> are a lot of way to build components for a given board and I am worry of 
> the overheard for the maintainers to look/maintain the documentation. It 
> also brings the question of the acceptance/removal of
> a board documentation.

That problem can be solved by specifying an appropriate maintenance
model for those documents.


> Instead we should provide generic guidance/troubleshoot to the user. 
> Anything board specific could be maintain on the wiki by someone caring 
> about the board without having us to gate it.

If we move the docs to xen.git it doesn't immediately imply that the
REST maintainers need to "gate" them. We could make the existing
curators of those pages the maintainers for those files, for example. We
can come up with mode ideas. We could even leave them unmaintained.

The point here is that we can be flexible and creative about the way to
maintain the docs on xen.git. But as a technology is certainly better
than the wiki: we don't have to keep them all up-to-date with the code,
but at least this way we have a chance (if we want to). If we leave them
on the wiki, there is no chance.


> We could try to revive a discussion we had a couple of years ago where 
> someone is responsible for a given board to test and document it. Today 
> it is informal, but I have been pushing for it recently for new boards.

Yes, this is a good idea and fit nicely with the maintenance model I
was suggesting.

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel