Re: [PATCH v3 1/3] docs: add documentation for Argo as a feature

[Christopher Clark <christopher.w.clark@xxxxxxxxx>]

On Sun, Jun 8, 2025 at 7:37 PM Rich Persaud <persaur@xxxxxxxxx> wrote:

On Jun 8, 2025, at 5:49 AM, Christopher Clark <christopher.w.clark@xxxxxxxxx> wrote:



On Wed, Jun 4, 2025 at 5:14 PM Jason Andryuk <jason.andryuk@xxxxxxx> wrote:

I think this should be dropped.  We don't need a link to a design
document without an implementation.  You can add it once you've
upstreamed the implementation.

OK, I'll remove this section for the next version of the series.

What's the recommended location of Xen design documents, requirements for future improvements, roadmaps or pointers to related work in adjacent open-source communities? The Xen wiki is being deprecated.

Others CCd are likely better qualified than I to answer these (reasonable) questions, and I am interested to learn from any further answers.

My preferred option is not to deprecate the wiki, or at least not without a replacement for it. I have found the wiki to be useful for many years for both publishing technical content and for access to helpful material not available anywhere else, even if the contents are rougher than the formal documentation. Its accessibility is an essential part of enabling that.

If the wiki is deprecated, the available alternatives appear to be:

* Pursuing formal acceptance of documents into one of the Xen git repositories;
From my experience of doing so, less documentation will be produced if this is the standard required and unique knowledge will be lost at an ongoing cost to both the developer community and users of Xen. Review capacity is already scarce and this will further deplete that.

* Publishing on the platforms of adjacent communities;
Documentation will be less discoverable and at the mercy of external tools and processes, again at a cost to collaboration within the Xen community.

* Repurposing the Xen issue tracker
This would be a horrible bodge. Please no.

* Self-hosting - similar to publishing in an adjacent community, but worse

I would prefer not to have to do this and may not have time available to do so. Not everyone is able to. 

* Replace the wiki with another collaboratively-edited document hosting platform

I am open to learning more about options for this if it is the recommended direction.

What's the recommended way for the Xen community to discover the existence of Argo documentation that is not hosted by the Xen community? If necessary, we can create a new semantic label or Xen docs directory tree, to host technical content that might otherwise be lost.

Should we add a sentence to Xen's Argo documentation, to the effect of "Please refer to the Xen [wiki in archive.org, website, mailing list], external sites [A, B, C, D], or your preferred [search engine, LLM] for more technical documents on Argo design and implementation"?

The Virtio & Argo design documents, produced within an adjacent community so they are hosted there, are relevant to Xen and ought to be enabled to be discoverable (and if necessary hostable) via Xen community platforms. They are also a single instance of a general class: there will be developments of other Xen-related features within XCP-ng, Qubes and Linaro projects - and other adjacent communities - that also warrant description and linking from within Xen community documentation.

To Jason's review point: I am willing to accept leaving the VirtIO section out of this specific Argo feature document but I do need an appropriate alternative place for it - eg. the Argo design document (already within the Xen source tree) could be extended to introduce it instead. The externally referenced design documents are part of how such future features get implemented, so referencing prior to implementation is helpful and supportive of the continued development of the technology.

Christopher