Contributing to Documentation¶

Xen Project documentation is spread across three homes. This page explains what belongs where, so that when you write something new it lands in the right place — and stays maintainable. It is aimed at anyone who wants to write or improve Xen documentation.

The deciding question is always: where does the source of truth live, and what does the documentation version with?

Documentation that describes the code, lives in the source tree, and is released alongside it belongs at xenbits.
Documentation about using Xen that reads as narrative and applies across versions belongs in the User Handbook.
Documentation about participating in the project belongs in this Contributor Handbook.

Where documentation lives¶

Home	What belongs there	Examples
xenbits (xenbits.xen.org/docs)	Reference documentation coupled to the code. It lives in `docs/` in `xen.git`, is versioned with each release, and is the canonical reference.	`xl` and `xenstore` man pages, hypercall and API references, design documents, feature specifications, MISRA/FUSA safety docs, the release and patch-submission process specs.
User Handbook (handbook.xenproject.org/users)	Narrative, accessible guidance for running Xen. Curated and cross-version; points to the xenbits reference rather than duplicating it.	Introduction to virtualization concepts, getting a dom0 running, creating guests, networking and storage setup, troubleshooting.
Contributor Handbook (this site)	How to take part in the project: community, process, and governance. Project-level, not code-level.	How to ask questions, how to submit patches, code review, reporting bugs, release planning, governance, teams.

Home

What belongs there

Examples

xenbits

(xenbits.xen.org/docs)

Reference documentation coupled to the code. It lives in docs/ in xen.git, is versioned with each release, and is the canonical reference.

xl and xenstore man pages, hypercall and API references, design documents, feature specifications, MISRA/FUSA safety docs, the release and patch-submission process specs.

User Handbook

(handbook.xenproject.org/users)

Narrative, accessible guidance for running Xen. Curated and cross-version; points to the xenbits reference rather than duplicating it.

Introduction to virtualization concepts, getting a dom0 running, creating guests, networking and storage setup, troubleshooting.

Contributor Handbook

(this site)

How to take part in the project: community, process, and governance. Project-level, not code-level.

How to ask questions, how to submit patches, code review, reporting bugs, release planning, governance, teams.

A few worked examples:

“A complete table of every ``xl create`` option” → xenbits (it is the xl man page, and it must match the shipped code).
“A walkthrough of setting up your first PV guest” → User Handbook.
“The design rationale for a new hypercall” → xenbits (a design document in docs/designs/).
“How patches get reviewed and what the review tags mean” → Contributor Handbook (Code Review).
“How the project decides on the next release date” → Contributor Handbook (Release Planning).

How to contribute to each¶

The workflow depends on which home you are editing.

Both handbooks¶

The Contributor Handbook and the User Handbook live in the same repository and use the same workflow: open a merge request against gitlab.com/xen-project/websites/handbook. Small changes are welcome as issues for someone else to commit, and rough drafts do not need to be polished — see the README for details. If you would like commit access, just ask.

xenbits documentation¶

Documentation on xenbits is part of the docs/ tree in xen.git. Change it the same way you change any other code in the tree: by sending a patch to the xen-devel mailing list. See Submitting Patches for the workflow.