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

[P S <pairspace@gmail.com>]

> On Jun 25, 2019, at 12:34, Lars Kurth <lars.kurth@citrix.com> wrote:
> 
> 
> 
> On 25/06/2019, 14:47, "Andrew Cooper" <Andrew.Cooper3@citrix.com> wrote:
> 
>>    On 25/06/2019 13:15, Lars Kurth wrote:
>> On 25/06/2019, 10:03, "Julien Grall" <julien.grall@arm.com> 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
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel