Re: [RFC v2 for-4.6 0/2] In-tree feature documentation

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

On 27/08/15 15:52, Ian Jackson wrote:
> Andrew Cooper writes ("[RFC v2 for-4.6 0/2] In-tree feature documentation"):
>> An issue which Xen has is an uncertain support statement for features.
>> Given the success seen with docs/misc/xen-command-line.markdown, and in
>> particular keeping it up to date, introduce a similar system for
>> features.
>>
>> Patch 1 introduces a proposed template (and a makefile tweak to include
>> the new docs/features subdirectory), while patch 2 is a feature document
>> covering the topic of migration.
>>
>> v2 Adds %Revision and #History table, following feedback from v1.
>>
>> This is tagged RFC as I expect people to have different views as to what
>> is useful to include.  I would particilarly appreciate feedback on the
>> template before it starts getting used widely.
>>
>> Lars: Does this look like a reasonable counterpart to your formal
>> support statement document?
>>
>> Jim: Per your request at the summit for new information, is patch 2
>> suitable?
> I have read both patches.
>
> I do wonder whether cross-referencing all the "issues" is a good idea.
> It seems like it might be a lot of work to keep them in step.

I don't expect all the issues to be enumerated (generally, they would be
found the first time someone falls over the issue), but where known
interaction issues exist, we need to have some place to leave them.

There are plenty of examples where known issues are documented somewhere
in the xen-devel archives, or in an individuals head, and neither of
these are useful places for the information to exist.

I would hope that over time the number of issues decreases to 0 (that
would be the day!), but a good second is at least to have a formal
acknowledge that there are issues, which can be located by the next
unfortunate sole to hit the issue.

>
> I don't have anything else to add to the comments that others have
> made.
>
> Overall I think this is a good template.  The extra overhead may even
> be negative.  The work of writing up a feature in the style of this
> document may obviate the need to put much of the same information in a
> 0/N or a design document, and the existing template is quite
> lightweight.

I hadn't considered this side benefit when designing the template.

~Andrew