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

[Andrew Cooper <andrew.cooper3@citrix.com>]

On 24/08/2015 20:27, Juergen Gross wrote:
> 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
>

In the longterm, I would expect that information to be visible via `git
log`.

Having said that, it probably is useful to have a summary of history
available in the written document.

How about a #History section at the bottom?  That can at least include
"document written" as a starting point and subsequent major changes in
short form.

~Andrew