[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

On 08/24/2015 07:37 PM, Andrew Cooper wrote:
Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
  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' 

  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' 

  # 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
+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
+# 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


+# Overview
+A short description the feature, similar to an abstract for a
+# 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
+# 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

Xen-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.