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 <j...@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@lists.openstack.org
> :http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>
> --
>
> _______________________________________________
> OpenStack-operators mailing list
> OpenStack-operators@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ OpenStack-operators mailing list OpenStack-operators@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
