cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jessica Tomechak <jessica.tomec...@gmail.com>
Subject Re: FW: [DOCS] links within a document.
Date Fri, 17 Aug 2012 07:29:48 GMT
>
> -----Original Message-----
> From: Joe Brockmeier [mailto:jzb@zonker.net]
> Sent: Thursday, August 16, 2012 2:32 PM
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: [DOCS] links within a document.
>
> On Thu, Aug 16, 2012 at 03:37:33PM -0400, sebgoa wrote:
> > David, IMHO we need to decide on what guides we want to have for 4.0(I
> > have not seen such discussion), it will be a subset of all the
> > documentation we have out there. Then we work on migrating the rest
> > (what is not in publican fmt right now) as well as updating/correcting
> > it.
>
> I think for the 4.0 release we should have:
>
> - Full Install Guide
> - Admin Guide
> - Developer's Guide
> - Runbooks
>
> A Runbook for KVM and XenServer/XCP at a minimum.
>
> > I don't think we should automate right now, we should do a manual
> > configuration of couple guides that are going to build for the release.
> > We could decide on that during the IRC meeting. Then Joe can build
> > them :)
>
> As David said, we can discuss this - but decisions will be taken on the
> mailing list.
>
> I'm happy to build the guides for the release, of course, if that's how we
> wind up doing things.
>
> Best,
>
> Joe
> --
> Joe Brockmeier
> http://dissociatedpress.net/
> Twitter: @jzb
>

Joe, thanks for your offer to manually generate various books for the
release. I'd  be more inclined to suggest that we simply generate
publican-all, one doc set/website with one "chapter" per task: install,
provision, administer, troubleshoot, develop against the API, etc. I don't
think our docs are so long that having them all in one "book" is a burden,
particularly if people will be sensible and read them in HTML.

A single output artifact is simpler to achieve. Partly because it
introduces fewer wrinkles to debug in time for 4.0, such as those pesky
links that break when the destination file isn't <include>d in a particular
book.

A second note: We don't yet have the runbooks Joe mentions, do we? If not,
I'm not sure it is wise to try to add new books when the release date is so
near. Documents need time to be reviewed and tested just as code does.
Also, I'd like more specifics about what you mean by the term "runbook."
David wrote something under that name that I'd call more like a custom
installation guide.

Jessica T.
CloudStack Tech Pubs

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message