|sebgoa||Sep 2, 2013 8:19 am|
|Alexander Hitchins||Sep 2, 2013 8:54 am|
|sebgoa||Sep 2, 2013 9:52 am|
|Ian Duffy||Sep 2, 2013 12:30 pm|
|Alexander Hitchins||Sep 2, 2013 12:41 pm|
|Sebastien Goasguen||Sep 2, 2013 12:45 pm|
|Ian Duffy||Sep 2, 2013 12:53 pm|
|Sebastien Goasguen||Sep 2, 2013 12:55 pm|
|Ian Duffy||Sep 2, 2013 1:06 pm|
|Sebastien Goasguen||Sep 2, 2013 1:36 pm|
|Prasanna Santhanam||Sep 3, 2013 12:09 am|
|Tracy Phillips||Sep 3, 2013 8:32 am|
|David Nalley||Sep 3, 2013 4:39 pm|
|Animesh Chaturvedi||Sep 3, 2013 5:26 pm|
|Sebastien Goasguen||Sep 4, 2013 12:08 am|
|Tracy Phillips||Sep 4, 2013 5:39 am|
|Tracy Phillips||Sep 4, 2013 5:50 am|
|Chip Childers||Sep 4, 2013 6:22 am|
|Travis Graham||Sep 4, 2013 6:53 am|
|Radhika Puthiyetath||Sep 4, 2013 7:43 am|
|sebgoa||Sep 4, 2013 8:39 am|
|Radhika Puthiyetath||Sep 4, 2013 8:52 am|
|Subject:||Re: [DOCS] feedback|
|Date:||Sep 4, 2013 8:39:41 am|
On Sep 4, 2013, at 4:43 PM, Radhika Puthiyetath <radh...@citrix.com>
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
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
We need to figure out how best to improve them, it may be that this involves
changing the format, it may not.
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:
After seeing lots of frustrated people with folks I decided to try something out
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.
There are two "books" aimed at being step by step recipes. Not long, not
convoluted, single OS, etc...simple step by step.
I am still sanitizing the installation one based on 4.2 .
Comments, flames ?
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
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.
Definitely talking about 4.3