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

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 25/06/2019 17:34, Lars Kurth 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.

It is a positive feedback cycle.  Noone uses our documentation because
its terrible, so the documentation stays in a terrible state.

As soon as the docs start to improve, the awareness will improve.

That said, there is still a responsibility for maintainers to be aware
of the documentation for their own areas, and to ensure the
documentation is maintained to the same high standard as we expect from
our code.

>
> 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.

Absolutely.  "how to submit changes" is one of the most cited wiki
pages, and having that in sphinx will cause loads of people to be aware
that we do have other docs in sphinx as well.  The fact that everything
is properly indexed is a massive benefit here.

~Andrew

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