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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Tue, 25 Jun 2019, Julien Grall 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.

Is the goal to keep the documentation fully up-to-date, or more
up-to-date than what we currently have on the wiki? I don't see this as
black and white. There are lot of stages of "up-to-dateness" in between.


> > > 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.
> 
> You actually haven't addressed my concern above. If you look at the wiki, a
> lot of them ([1], [2], [3]) contains non-upstreamed work or non-upstreamable
> hack.
> 
> For those containing only upstream work [4], the example is focusing on one
> set of distros. In the case of QEMU, I already had some people asking whether
> it is possible to use without U-boot. Why would we promote Ubuntu and not
> something else?
> 
> Overall, there are so many configurations possible (kernel, u-boot,
> distributions) that it does not makes sense to keep track of that in xen.git.
> 
> Instead, I think we should write generic doc on how to boot Xen on a
> U-boot/UEFI setup and inviting the users to look into more details for his
> board.

I don't think that we should host non-upstreamable hacks in general
either in xen.git. However, some boards require specific Linux kernel
trees to boot that are not upstream, so there is a fine line between
"non-upstreamable hack" and "following the docs and code provided with a
given board".

Similarly, I don't think we should have distro-specific information in
xen.git (or the wiki) either but sometimes we need to pick one as an
example. Otherwise, the tutorial wouldn't be complete.

In the case of the board specific files, we do both these things, but
because they are unavoidable, not because somebody wanted to advertise
Ubuntu, or preferred to use a private Linux kernel tree over upstream.
If that is the case, we should not import them into xen.git.

I also agree with you that if we are going to host only docs 100%
accurate, generic, and fully maintained by us on xen.git, then we should
NOT have the board specific docs there. But I would say that there is a
benefit in having docs not maintained by us and potentially not fully
up-to-date on xen.git that are useful to the community, like the board
specific docs. It would be easier to keep them "somewhat up to date"
release by release compared to the wiki, and in the future turn them
into "fully up to date" docs if we get more engagement.

If we leave them in the wiki I have the impression that their only
possible future is to rot and die...

This is not something that is going to happen anytime soon, so I think
we should take Lars' suggestion and talk about it at the Summit.

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