Re: [Xen-devel] Xen document day (Oct 12 or 26)

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Tue, 2011-09-27 at 23:18 +0100, Daniel Castro wrote:
> On Wed, Sep 28, 2011 at 2:13 AM, Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx> 
> wrote:
> > Konrad Rzeszutek Wilk writes ("Re: [Xen-devel] Xen document day (Oct 12 or 
> > 26)"):
> >> [ docs todo list ]
> > ...
> >> Who wants to do what? I created a sign up sheet:
> >>
> >> https://docs.google.com/spreadsheet/ccc?key=0Aj5ukWh4htwMdEFLVWpjRmx3VXdETDExNlByamd4Rmc&hl=en_US
> >>
> >> in case folks want to get an idea of who is doing what and not
> >> step on each toes.
> >
> > Daniel, I see you have put yourself down for some things to do with
> > "PDF manual".  I'm not sure exactly what you mean.  Do you mean the
> > user manual or the internals ("interface.tex") ?
> >
> > I think that both of these TeX documents really need to be abolished.
> > They're too hard to maintain so they have rotted; even if we were to
> > fix that they wouldn't stay up to date.
> 
> I was meaning the interface document. My current work involves
> interacting with almost all parts of that document, so giving C
> examples was very easy for me

I think these examples would be useful but I agree with Ian that
interfaces.tex is not the right place for them since we'd like to remove
it in favour of something maintainable.

Since the guest APIs are stable there should be relatively little churn
so perhaps a wiki page (or even series of pages) would be appropriate
for this sort of thing?

> For example there is no official guide on how to build Xen on a new
> system, and it took me several days to have a working system.

I think this would be good too and in fact even more important than the
interface documentation. Everyone needs to be able to build Xen to hack
on it but only a subset need to know any particular API.

Also although we recommend that users consume Xen via their distro where
possible such a guide would also help any who would rather build from
scratch (e.g. because we've asked them to "try the latest version" or to
bisect a bug etc).

Ian.

>  When
> developing code, in my case most of the needed documentation came from
> The Definitive Guide to Xen Hypervisor from PrenticeHall Press. But
> its becoming outdated now, sadly. And in some few cases it is very
> general and lack much needed detail. I do understand that Xen is huge
> and making a easy guide for everything is impractical.
> 
> Let me know how I can help, I really do want to help.
> 
> >
> > I have volunteered to do some manpage-style or markdown docs for xl.
> >
> > Ian.
> >
> 
> 
> 



_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel