Open Stack

Hi,

I have already manually created PDF versions of about 8 of the OpenStack Manuals (within about 4-6 hours including setting up the tool chain and locally fixing some bugs), and working on getting the rest done (at least those that are in the openstack-manuals.git repository) within the next few weeks, and make them available to the public. I’m currently working on an at least 3-phase approach:

phase 1) get as many of the docs in git (openstack-manuals.git ) as possible (mostly manually) converted to PDF and publish an URL where you can download them.

phase 2) set up a local build pipeline in our own OpenStack cloud to regularly convert the latest git versions to PDF e.g. every night, and publish them to the same location, possibly also providing docs for different versions (e.g. mitaka, neutron, ocata)

phase 3) work with the docs PTL (Lana) or whoever can help with it to set up the build process on the regular OpenStack / Ubuntu or whatever build environments so that the build process possibly could run on the standard build servers, and no longer on our own machines. Maybe the PDF version will not yet be a gate in the build process, but it should at least be flagged as a warning when there are errors, so the right people can look into it and try to fix it soon, without holding up the rest of the build and release process.

I was about to contact Lana in Barcelona, and we did meet 2 times, but we were both too busy with other meetings so didn’t get to talk about this in Barcelona, but I should be able to track her down on IRC or email or some other way soon (hopefully, if schedule permits it ;-) )

I absolutely see a case for PDF files, maybe some time also epub or mobi, and the tool chain already includes Sphinx as far as I know, which already provides the ability to create (La)TeX files which then can easily be typeset into PDF format, probably a few others as well (unfortunately I also didn’t have time to track down the Sphinx author, but at least got a lead on that).

HTML is fine for online viewing, but any time you sit in an airplane (e.g. from or to the Summit) or in a train with bad Internet connectivity, you’d need to download the whole HTML source tree, which is much more of a hassle than if you could just download a PDF or e-book file.

Also even in todays time there are still people who prefer a printed copy rather than some online doc, e.g. for sitting at the couch and have the feeling of real paper in your hand, or for taking it to the beach. I’m thinking about setting up a link somewhere on the docs site where you can order a printed copy (e.g. some books-on-demand provider) where you can at any time order a printed version of the latest doc version. I’ve even ran into to a “collector” type of person in Barcelona who likes to have all the books, but usually doesn’t even have time to read them, just the good feeling of having a lot of beautiful or interesting books… Sure, this is not everybody’s opinion about book formats, and many just like the HTML version (which will of course stay nevertheless), but if there are only 2 to 5 percent of all OpenStack users who’d like a PDF or printed version, this will still be in the hundreds I’d guess, maybe thousands

I also urgently request that the existing .Epub and .Mobi versions are kept at least in some “archives” location, since those are so far the only examples (that I know of) of carefully edited versions of the book, even though they are a bit outdated. Not sure if O’Reilly has some sort of copyright on the looks of the Ops book (we certainly cannot copy the front page with the "crested agouti” animal), but in my opinion it can at least be used as an example to how the future PDF and printed versions of the Ops book might look like, also including Table of Contents, an Index, and a Colophon.

I will certainly keep a copy of these 2 files around, and I strongly suggest to keep a copy on some publicly available location (if need be, I will provide that copy on our servers and make it available to anyone interested in them).

Just my 2 cents, and no, I’m not yet committing to all of this, just my current thoughts (Steve Martinelli, I heard you in the panel… "Do not over commit!”)

Cheers,

/lutz



> On 31 Oct 2016, at 18:10, Jonathan D. Proulx <jon at csail.mit.edu> wrote:
> 
> 
> I always use the HTML versions and can't think of a case where I'd
> want the epub or mobi.
> 
> If they are also out dated I definitly think they should be removed
> just to prevent confusion.
> 
> If there's a wider desire for these formats (which I doubt) then
> they'd need to be published much more frequently. I would be
> surprised if there were a need for this and just dropping them is
> likely the best option.
> 
> -Jon
> 
> On Mon, Oct 31, 2016 at 05:51:44PM +0100, Andreas Jaeger wrote:
> :Operators, a quick question from the docs team:
> :
> :We currently publish a frozen epub and mobi version of the O'Reilly
> :Operations Guide - in the version from 20th May 2014. This is now quite
> :different from the HTML version.
> :
> :The same for the Architecture Design Guide. Our epub is frozen and from
> :from 30th October 2014.
> :
> :We plan to add current PDFs for these documents in the Ocata cycle.
> :
> :Is there any reason these ancient epub/mobi versions should still get
> :published?
> :
> :Andreas
> :-- 
> : Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
> :  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
> :   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
> :       HRB 21284 (AG Nürnberg)
> :    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
> :
> :
> :_______________________________________________
> :OpenStack-operators mailing list
> :OpenStack-operators at lists.openstack.org
> :http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
> 
> -- 
> 
> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 6404 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-operators/attachments/20161031/e3560ca7/attachment.bin>