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

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. 

What happens today for many of these type of docs and/or processes is that:
a) We have discussion about a process / working practice on the list until we 
come to a conclusion
b) Then we take it and copy it to the wiki
Why not merge this into one activity

Both of you are interested in Arm docs, but this is something I will let you 
fight out. 
Maybe you want to chat about this some more at the summit

    >> But my point here is most of the board should be trivial. The most of the
    >> non-trivial setup require non-upstream patch. While I am happy to see 
that on
    >> the wiki, I think xen.git should not promote such configuration at all. 
We are
    >> working upstream, not with unknown/untrusted stack.
    >>
    >> For some working fully upstream, I don't think xen.git should promote any
    >> distros/versions of the kernel. However, this is ok on the wiki.
    > 
    > I would like to see the wiki disappear completely in the long term. As
    > we are moving more content to xen.git, it is not a good idea to have two
    > places where we keep information, for similar reasons why you suggested
    > to use in-code comments instead of docs to document interfaces. It
    > just takes more efforts to maintain information in two places and they
    > tend to get out of sync with each others.
    > 
    > If we make the wiki go away (I hope so), we'll need a place to store the
    > Arm board-specific documents, and other tutorials.
    
    Removing the wiki is an honorable goal, however I don't think all the wiki 
is 
    suitable for xen.git. The Arm board-specific documents is an example.

Removing the wiki was not my aim. The wiki is useful in some cases, but not in 
others.

Lars
    
    

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