Re: [Xen-devel] Migrating key developer docs to xen.git sphinx docs and refreshing them in the process

[Rich Persaud <persaur@xxxxxxxxx>]

> On Jun 25, 2019, at 12:34, Lars Kurth <lars.kurth@xxxxxxxxxx> wrote:
> 
> On 25/06/2019, 14:47, "Andrew Cooper" <Andrew.Cooper3@xxxxxxxxxx> wrote:
> 
>>   On 25/06/2019 13:15, Lars Kurth wrote:
>> On 25/06/2019, 10:03, "Julien Grall" <julien.grall@xxxxxxx> wrote:
>> 
>>>>> The point here is that we can be flexible and creative about the way to
>>>>> maintain the docs on xen.git. But as a technology is certainly better
>>>>> than the wiki: we don't have to keep them all up-to-date with the code,
>>>>> but at least this way we have a chance (if we want to). If we leave them
>>>>> on the wiki, there is no chance.
>>>> 
>>>> I can't see how xen.git is going to be better if "we don't have to keep 
>>>> them
>>>> all up-to-date".
>>> 
>>> That's because a contributor could add a patch at the end of a series to
>>> update one of the docs, even if the doc in question comes with no
>>> promises of being up-to-date.
>> 
>>   I think this is going the wrong direction. The goal of using xen.git is to 
>> try 
>>   to keep the documentation up-to-date.
>> 
>> I agree with Julien and this was also not my intention. The reason why I 
>> brought this up now is that the in-tree docs are pretty much a mess today 
>> and are stale in many ways. And they look TERRIBLE and are not easily 
>> searchable. However, Andy's latest set of patches provide an opportunity to 
>> consolidate some of the in-tree docs in a nicely rendered and searchable 
>> format.
> 
>   So the plan here is to get a consistent and uniform set of high quality
>   docs.
> 
>   As fair warning, I'm intending to be fairly strict with what goes in
>   (quality wise), because I'm going to do my best to ensure that the
>   sphinx documentation doesn't devolve into the mess that wiki or the
>   majority of docs/ currently is.
> 
> I wholeheartedly agree
> 
>> I have been focussing on process related and key developer related docs, 
>> because who maintains them is not actually an issue in theory. Everyone 
>> really ought to care, because everyone is impacted by these.
> 
>   The key point is for maintainers/reviewers to be aware of whether
>   documentation exists for the area of code being modified, and if so,
>   whether the submitted patch should also patch the documentation.
> 
> I am wondering whether this is something which could be addressed. One 
> possibility may be to have SUPPORT.md point to documentation. But that is 
> kind of assuming that SUPPORT.md works and is widely used. There may be 
> better or orthogonal ways to point to relevant docs (e.g. by pointing to docs 
> in header files and other source files). 
> 
>   Reviewers tend to be fairly good at noticing patches which also need to
>   patch docs/misc/xen-command-line.pandoc (submitters, less so), but this
>   approach needs extending to the whole of the sphinx docs (which in turn
>   requires the docs to stay high quality so its easy for maintainers to
>   know what is where).
> 
> Although this does not apply in my proposal, I think the key issue has been 
> that reviewers and submitters of code often don't use our documentation. The 
> wiki is seen as a separate thing and also has the disadvantage that it 
> doesn't lend itself to supporting different versions of Xen. And most of the 
> time, developers do not use it and neither contribute to it.
> 
> My hope was that by hosting documentation related to contribution workflow 
> and other essential tasks close to other useful documentation this would 
> enable change.
> 
> @Andy and others: I need to know whether you agree with my proposal and 
> whether anyone has other suggestions.

If not already present in the release manager process checklist, we could 
specify documentation-related updates for each release, e.g. minimum text for 
new features, revisions to modified features, SUPPORT.md updates.

Rich

(resend with non-bulkmail address)
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel