On Fri, Aug 17, 2012 at 12:29:48AM -0700, Jessica Tomechak wrote: > 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.
Depends on your definition of "so long," I guess. The current install guide alone is 153 pages (PDF), the admin guide is 133, etc. My thought when I picked them up to get started with CloudStack is that they are well-done, but a bit ungainly. Administer as a single chapter, for instance, would be a pretty big hunk of documentation. > 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. It would be simpler to achieve, yes. I'm just not sure it's as desirable. > 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. I was using the term to mean a similar guide to what David developed for setting up a simple CloudStack install with KVM/CentOS. -- Joe Brockmeier http://dissociatedpress.net/ Twitter: @jzb
