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

[Lars Kurth <lars.kurth@xxxxxxxxxx>]

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.

Regards
Lars
 


 
    
    

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel