atom feed22 messages in org.apache.incubator.cloudstack-devRe: [DOCS] feedback
FromSent OnAttachments
sebgoaSep 2, 2013 8:19 am 
Alexander HitchinsSep 2, 2013 8:54 am 
sebgoaSep 2, 2013 9:52 am 
Ian DuffySep 2, 2013 12:30 pm 
Alexander HitchinsSep 2, 2013 12:41 pm 
Sebastien GoasguenSep 2, 2013 12:45 pm 
Ian DuffySep 2, 2013 12:53 pm 
Sebastien GoasguenSep 2, 2013 12:55 pm 
Ian DuffySep 2, 2013 1:06 pm 
Sebastien GoasguenSep 2, 2013 1:36 pm 
Prasanna SanthanamSep 3, 2013 12:09 am 
Tracy PhillipsSep 3, 2013 8:32 am 
David NalleySep 3, 2013 4:39 pm 
Animesh ChaturvediSep 3, 2013 5:26 pm 
Sebastien GoasguenSep 4, 2013 12:08 am 
Tracy PhillipsSep 4, 2013 5:39 am 
Tracy PhillipsSep 4, 2013 5:50 am 
Chip ChildersSep 4, 2013 6:22 am 
Travis GrahamSep 4, 2013 6:53 am 
Radhika PuthiyetathSep 4, 2013 7:43 am 
sebgoaSep 4, 2013 8:39 am 
Radhika PuthiyetathSep 4, 2013 8:52 am 
Subject:Re: [DOCS] feedback
From:sebgoa (run@gmail.com)
Date:Sep 4, 2013 8:39:41 am
List:org.apache.incubator.cloudstack-dev

On Sep 4, 2013, at 4:43 PM, Radhika Puthiyetath <radh@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: de@cloudstack.apache.org Subject: Re: [DOCS] feedback

On Sep 3, 2013, at 7:39 PM, David Nalley <dav@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.mar kdown https://github.com/runseb/cloudstack-books/blob/master/en/installatio 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