Hi Sebastien, I am game. I am all there to do anything to enhance the documentation.
As far as I know, API documentation is not in good shape. I heard about Installation Guide, as well. I would also like to know what are the improvement areas around the Administration Guide. We can take it as a project, define deadlines, and deliver one at a time. Any suggestions? Regards -Radhika -----Original Message----- From: sebgoa [mailto:run...@gmail.com] Sent: Wednesday, September 04, 2013 9:10 PM To: dev@cloudstack.apache.org Subject: Re: [DOCS] feedback On Sep 4, 2013, at 4:43 PM, Radhika Puthiyetath <radhika.puthiyet...@citrix.com> wrote: > Hi, > > Could someone enlighten me with the various reasons for making a strategic > change in the tools we use for documentation ? > > I loved DocBook and publican. > > What are the advantages of having the new system in place other than a new > look and feel? > > I am open to learning, but how easy for a writer to pick up the new mechanics > if the community has already arrived at a consensus about this? > Radhika, this is just a discussion right now. The problem is not really Docbook, the problem is that the docs are not in good shape. We need to figure out how best to improve them, it may be that this involves changing the format, it may not. -sebastien > Thanks > -Radhika > > -----Original Message----- > From: Sebastien Goasguen [mailto:run...@gmail.com] > Sent: Wednesday, September 04, 2013 12:39 PM > To: dev@cloudstack.apache.org > Subject: Re: [DOCS] feedback > > > 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.ma >>> r >>> kdown >>> https://github.com/runseb/cloudstack-books/blob/master/en/installati >>> o >>> n.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 >
