Re: [PATCH for-4.6 1/2] docs: Template for feature documents

[Juergen Gross <xen@pfupf.net>]

On 08/24/2015 07:37 PM, Andrew Cooper wrote:
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> ---
>   docs/Makefile                 |    2 +-
>   docs/features/template.pandoc |   55 +++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 56 insertions(+), 1 deletion(-)
>   create mode 100644 docs/features/template.pandoc
>
> diff --git a/docs/Makefile b/docs/Makefile
> index 272292c..5d620e5 100644
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -16,7 +16,7 @@ MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
>
>   TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print))
>
> -PANDOCSRC-y := $(sort $(shell find specs -name '*.pandoc' -print))
> +PANDOCSRC-y := $(sort $(shell find features/ misc/ specs/ -name '*.pandoc' -print))
>
>   # Documentation targets
>   DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y))
> diff --git a/docs/features/template.pandoc b/docs/features/template.pandoc
> new file mode 100644
> index 0000000..d883b82
> --- /dev/null
> +++ b/docs/features/template.pandoc
> @@ -0,0 +1,55 @@
> +% Template for feature documents
> +
> +\clearpage
> +
> +This is a suggested template for formatting of a Xen feature document in tree.
> +
> +The purpose of this document is to provide a concrete support statement for the
> +feature (indicating its security status), as well as brief user and technical
> +documentation.
> +
> +# Basics
> +
> +A table with an overview of the support status and applicability.
> +
> +---------------- ----------------------------------------------------
> +         Status: e.g. **Supported**/**Tech Preview**/**Experimental**
> +
> +Architecture(s): e.g. x86, arm
> +
> +   Component(s): e.g. Hypervisor, toolstack, guest
> +
> +       Hardware: _where applicable_
> +---------------- ----------------------------------------------------

What about adding some information when the feature was introduced or
some other historical stuff? Something like:

Experimental in Xen 4.1
Supported in Xen 4.3
xl syntax changed in Xen 4.4


Juergen

> +
> +# Overview
> +
> +A short description the feature, similar to an abstract for a
> +paper/presentation.
> +
> +# User information
> +
> +Information for a user attempting to use the feature.  Should include how to
> +enable the feature (is it enabled by default? If not, how to turn it on?), and
> +how to interact with the feature (typically via `xl`).
> +
> +# Limitations
> +
> +Information concerning incompatibilities with other features or hardware
> +combinations.
> +
> +# Technical information
> +
> +Information for a developer or power user.  Should include where to look
> +in-tree for detailed documents and code.
> +
> +# Areas for improvement
> +
> +List of enhancements which could be undertaken, e.g. to improve the feature
> +itself, or improve interaction with other features.
> +
> +# Known issues
> +
> +List of known issues or bugs.  For tech preview or experimental features, this
> +section must contain the list of items needing fixing for its status to be
> +upgraded.
>