Xen Summit 2025 - "Documentation Next Steps" design session notes

["Yann Sionneau" <yann.sionneau@xxxxxxxxxx>]

"Documentation Next Steps"
(https://design-sessions.xenproject.org/uid/discussion/disc_Jp2T9yq2I3sH00teD0CT/view)
design session notes

Animated by Cody.

The documentation kind of exist…
There’s the wiki but you cannot register: it’s deactivated.
We had to put a control system because some people were crashing the
wiki content.
Cody : the technical documentation is being created in Sphinx
It’s hard to find getting started, documentation and guides.
It’s in the wiki but it also contain outdated documentation.
Problem of the wiki is that it’s not related to some Xen version.
Sphinx is at least tied to some Xen version.
The wiki also contains how-to’s, list of boards, things that don’t
really make sense in xen.git but are helpful to people.
If we write pages on the website the number of person to contribute to
this will be limited.
The website is in a git repo now
(https://gitlab.com/xen-project/www-xenproject-org)
Some wiki pages are outdated because they are only valid for some
versions of Xen.
We should have a getting started guide which is well maintained.
We could have some information in the wiki like specific getting started
for some specific boards and then put the link to the wiki pages in the
website.
Real documentation should not be on the wiki because it’s getting out of
date and is not tied to Xen versions.
We should prevent people from writing “git clone xen.git; make” in the
wiki, we should always provide branch/tags/sha1 so that the information
stays true.
It’s OK to have some outdated info, it’s better than having no info at all.
We need to write more doc/info.
Also, what do we put in the documentation for instance to explain how to
put Xen on an RPI? Since we don’t maintain yocto meta-virtualization.
How do we provide the domU?
We should have a user documentation auto generated from git repo (sphinx?)
So first we would need to convert current doc (in xen.git and some parts
of the wiki) into sphinx format. Before then adding new content.
We need to link to the new sphinx doc in the website
(https://xenbits.xen.org/docs/sphinx-4.20-testing/ for instance).
- need a list of supported boards, should be listed on the website
We should put some text in the getting started to say “if you have
difficulties, please email xen-users mailing list”


--


--
Yann Sionneau | Vates XCP-ng Developer

XCP-ng & Xen Orchestra - Vates solutions

web: https://vates.tech