From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ian Campbell Subject: Re: Xen document day (Oct 12 or 26) Date: Wed, 28 Sep 2011 08:40:56 +0100 Message-ID: <1317195656.13424.73.camel@dagon.hellion.org.uk> References: <20110922130618.GA13238@phenom.oracle.com> <20110922174002.GA1205@phenom.oracle.com> <20098.1097.824552.541924@mariner.uk.xensource.com> Mime-Version: 1.0 Content-Type: text/plain; charset="ISO-8859-1" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xensource.com Errors-To: xen-devel-bounces@lists.xensource.com To: Daniel Castro Cc: "xen-devel@lists.xensource.com" , Ian Jackson , Rzeszutek Wilk , Konrad List-Id: xen-devel@lists.xenproject.org On Tue, 2011-09-27 at 23:18 +0100, Daniel Castro wrote: > On Wed, Sep 28, 2011 at 2:13 AM, Ian Jackson 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. > > > > >