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

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

On 25/08/15 09:41, Wei Liu wrote:
>
>>>> +
>>>> +\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.
> Or use a table for revision history at the beginning? I personally think
> using a table is clearer than several paragraphs.
>
> Don't want to bikeshed how it should look like. We can always change the
> template if necessary.

I have introduced a history table at the end of the template.  I want to
avoid it getting in the way of the table of basic information and overview.

~Andrew