On Mon, Sep 2, 2013 at 11:19 AM, sebgoa <run...@gmail.com> wrote: > Hi, > > After seeing lots of frustrated people with folks I decided to try something > out with markdown. > > I used pandoc to convert some docbook files to markdown and I used a > structure for a book based on 'The little mongodb' book. > We can generate epub and pdf using latex. > > See: > > https://github.com/runseb/cloudstack-books > > There are two "books" aimed at being step by step recipes. Not long, not > convoluted, single OS, etc…simple step by step. > > https://github.com/runseb/cloudstack-books/blob/master/en/clients.markdown > https://github.com/runseb/cloudstack-books/blob/master/en/installation.markdown > > I am still sanitizing the installation one based on 4.2 . > > Comments, flames ? > > -Sebastien >
So you are essentially talking about moving to MD from Docbook - is this for all of the docs? Joe and I looked at this briefly at CCC - most of the MD tools seemed to use LaTeX or converted to DocBook to publish to PDF or Epub - which placed constraints on what DocBook tags were available as well as what subset of MD was supported. My concerns would be: How do we handle reusability? How do we handle l10n I am not necessarily against giving up on either of those, but, if we are ditching those, we need to do so explicitly and make sure we have consensus around those impacts. I know we have issues, esp for newcomers attempting their first installation. It's one of the reasons I started working on the Runbook/QIG many moons ago. I just don't know if it's better or worse for us to also toss our existing tooling in the process of fixing the documentation. There is a lot that exists now that we'd have to recreate (or throw out and rewrite.) And if we really want to do that, do we want to do it now or for 4.3 or $someothertimeframe. 4.2 docs are currently what terrify me because of the timeline to release. --David --David
