On Sep 3, 2013, at 7:39 PM, David Nalley <da...@gnsa.us> wrote: > 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?
Not really. We need to fix our docs and the question is how best to do that ? We can keep Docbook but that probably means writing brand new docs, breaking up OS in different books and finding a release mechanism so that we can update faster than a release. I merely used markdown because it's easy to take notes in .txt as you are testing things. > > 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 We could still use transifex > > 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. > Yes, so how best to drive this discussion forward, this goes with other thread about the wiki and the website. > 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 Definitely talking about 4.3 > > > > --David
