You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Jessica Tomechak <je...@gmail.com> on 2012/09/20 20:59:01 UTC

[DOCS] Using DITA vs. Docbook for documentation?

Recently someone from the docs world asked me why we are using Docbook +
Publican for our documentation, rather than DITA. I gave a reasonable
reply, but in the end, I thought it would be worth bringing the topic up
here. For the record, I'm not proposing or advocating anything. Just
looking for the community temperature.

Some benefits listed by this DITA advocate I was speaking with:

Simpler tagging than Docbook

It’s open source, has open source community developing useful plugins, such
as latest webhelp output

Can create several different website outputs

Please discuss!

Jessica T.
CloudStack Tech Pubs

Re: [DOCS] Using DITA vs. Docbook for documentation?

Posted by Jessica Tomechak <je...@gmail.com>.
-----Original Message-----

> From: Gavin Lee [mailto:gavin.lxh@gmail.com]
> Sent: Wednesday, September 26, 2012 6:25 PM
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: [DOCS] Using DITA vs. Docbook for documentation?
>
> +1 for Docbook + Publican.
> imho, it's not the right time to switch the tool even DITA is better:
> a) Docbook can do almost everything we need at this moment, the html
> output is pretty good.
> b) Still need to hurry up on docbook, change to DITA may cost even more
> time to hit the release
> c) L10N part is easy to contribute on transifex based on po files
> generated by publican, not sure DITA
>
> If DITA is still better, think about using it in next major release(may be
> not 4.1).
>
>
> On Thu, Sep 27, 2012 at 5:18 AM, David Nalley <da...@gnsa.us> wrote:
> >> I don't have a real opinion on which format is really 'the best', but
> >> I do agree that we still have enough work to do with DocBook.
> >>
> >> Currently DocBook seems to do everything we need, so I don't see a
> >> real need for switching.
> >
> > I personally have opinions - but mainly around we have a group of
> > folks who are comfortable with DocBook and don't know about DITA. Why
> > fix what isn't broken?
> >
> > I do echo Wido's point - we have plenty of work to still do with our
> > existing documentation, and shifting our time to change format and
> > make everyone learn something new for what is arguably little or no
> > additional benefit seems like bikeshedding at best.
> >
> > --David
>


> --
> Gavin
>

Everyone here is stating the excellent reasons for staying with Docbook so
well. I have no quarrel with the sentiment expressed. Certainly, for the
foreseeable future, I don't see any compelling case for switching to DITA.
Thanks for weighing in.

Jessica T.
CloudStack Tech Pubs

Re: [DOCS] Using DITA vs. Docbook for documentation?

Posted by Gavin Lee <ga...@gmail.com>.
+1 for Docbook + Publican.
imho, it's not the right time to switch the tool even DITA is better:
a) Docbook can do almost everything we need at this moment, the html
output is pretty good.
b) Still need to hurry up on docbook, change to DITA may cost even
more time to hit the release
c) L10N part is easy to contribute on transifex based on po files
generated by publican, not sure DITA

If DITA is still better, think about using it in next major
release(may be not 4.1).


On Thu, Sep 27, 2012 at 5:18 AM, David Nalley <da...@gnsa.us> wrote:
>> I don't have a real opinion on which format is really 'the best', but I do
>> agree that we still have enough work to do with DocBook.
>>
>> Currently DocBook seems to do everything we need, so I don't see a real need
>> for switching.
>
> I personally have opinions - but mainly around we have a group of
> folks who are comfortable with DocBook and don't know about DITA. Why
> fix what isn't broken?
>
> I do echo Wido's point - we have plenty of work to still do with our
> existing documentation, and shifting our time to change format and
> make everyone learn something new for what is arguably little or no
> additional benefit seems like bikeshedding at best.
>
> --David



-- 
Gavin

Re: [DOCS] Using DITA vs. Docbook for documentation?

Posted by David Nalley <da...@gnsa.us>.
> I don't have a real opinion on which format is really 'the best', but I do
> agree that we still have enough work to do with DocBook.
>
> Currently DocBook seems to do everything we need, so I don't see a real need
> for switching.

I personally have opinions - but mainly around we have a group of
folks who are comfortable with DocBook and don't know about DITA. Why
fix what isn't broken?

I do echo Wido's point - we have plenty of work to still do with our
existing documentation, and shifting our time to change format and
make everyone learn something new for what is arguably little or no
additional benefit seems like bikeshedding at best.

--David

Re: [DOCS] Using DITA vs. Docbook for documentation?

Posted by Wido den Hollander <wi...@widodh.nl>.

On 09/26/2012 11:08 PM, Jessica Tomechak wrote:
>>
>>
>> -----Original Message-----
>> From: Joe Brockmeier [mailto:jzb@zonker.net]
>> Sent: Thursday, September 20, 2012 1:08 PM
>> To: CloudStack Developers
>> Subject: Re: [DOCS] Using DITA vs. Docbook for documentation?
>>
>> On Thu, Sep 20, 2012, at 01:59 PM, Jessica Tomechak wrote:
>>> Recently someone from the docs world asked me why we are using Docbook
>>> + Publican for our documentation, rather than DITA. I gave a
>>> reasonable reply, but in the end, I thought it would be worth bringing
>>> the topic up here. For the record, I'm not proposing or advocating
>>> anything. Just looking for the community temperature.
>>>
>>> Some benefits listed by this DITA advocate I was speaking with:
>>>
>>> Simpler tagging than Docbook
>>
>> How much simpler? Publican's tagging is pretty simple. It's not
>> Markdown-simple, but it's not that bad.
>>
>>> It’s open source, has open source community developing useful plugins,
>>> such as latest webhelp output
>>
>> Publican is also open source, so I don't see any benefit to DITA over
>> DocBook/Publican in that regard.
>>
>> Publican has PDF and HTML - it looks like Webhelp is just XHTML with
>> styling/etc. Is there anything native to webhelp that we don't get from
>> Publican's HTML output?
>>
>> We've already put a fair amount of effort into the existing Publican stuff
>> - so I'd want to see something pretty darn nifty to throw that out in favor
>> of a new format or have a tool that can easily convert Publican
>> -> DITA...
>>
>> Best,
>>
>> Joe
>> --
>> Joe Brockmeier
>> jzb@zonker.net
>> Twitter: @jzb
>> http://www.dissociatedpress.net/
>>
>
> Anyone else have an opinion on this?
>

I don't have a real opinion on which format is really 'the best', but I 
do agree that we still have enough work to do with DocBook.

Currently DocBook seems to do everything we need, so I don't see a real 
need for switching.

Wido

> Joe, thanks for the reply. I pretty much agree with all that you said. On
> the question of whether the webhelp format is something we need, or not:
> I'm not sure.
>
> Jessica T.
> CloudStack Tech Pubs
>

Re: [DOCS] Using DITA vs. Docbook for documentation?

Posted by Jessica Tomechak <je...@gmail.com>.
>
>
> -----Original Message-----
> From: Joe Brockmeier [mailto:jzb@zonker.net]
> Sent: Thursday, September 20, 2012 1:08 PM
> To: CloudStack Developers
> Subject: Re: [DOCS] Using DITA vs. Docbook for documentation?
>
> On Thu, Sep 20, 2012, at 01:59 PM, Jessica Tomechak wrote:
> > Recently someone from the docs world asked me why we are using Docbook
> > + Publican for our documentation, rather than DITA. I gave a
> > reasonable reply, but in the end, I thought it would be worth bringing
> > the topic up here. For the record, I'm not proposing or advocating
> > anything. Just looking for the community temperature.
> >
> > Some benefits listed by this DITA advocate I was speaking with:
> >
> > Simpler tagging than Docbook
>
> How much simpler? Publican's tagging is pretty simple. It's not
> Markdown-simple, but it's not that bad.
>
> > It’s open source, has open source community developing useful plugins,
> > such as latest webhelp output
>
> Publican is also open source, so I don't see any benefit to DITA over
> DocBook/Publican in that regard.
>
> Publican has PDF and HTML - it looks like Webhelp is just XHTML with
> styling/etc. Is there anything native to webhelp that we don't get from
> Publican's HTML output?
>
> We've already put a fair amount of effort into the existing Publican stuff
> - so I'd want to see something pretty darn nifty to throw that out in favor
> of a new format or have a tool that can easily convert Publican
> -> DITA...
>
> Best,
>
> Joe
> --
> Joe Brockmeier
> jzb@zonker.net
> Twitter: @jzb
> http://www.dissociatedpress.net/
>

Anyone else have an opinion on this?

Joe, thanks for the reply. I pretty much agree with all that you said. On
the question of whether the webhelp format is something we need, or not:
I'm not sure.

Jessica T.
CloudStack Tech Pubs

Re: [DOCS] Using DITA vs. Docbook for documentation?

Posted by Joe Brockmeier <jz...@zonker.net>.
On Thu, Sep 20, 2012, at 01:59 PM, Jessica Tomechak wrote:
> Recently someone from the docs world asked me why we are using Docbook +
> Publican for our documentation, rather than DITA. I gave a reasonable
> reply, but in the end, I thought it would be worth bringing the topic up
> here. For the record, I'm not proposing or advocating anything. Just
> looking for the community temperature.
> 
> Some benefits listed by this DITA advocate I was speaking with:
> 
> Simpler tagging than Docbook

How much simpler? Publican's tagging is pretty simple. It's not
Markdown-simple, but it's not that bad. 
 
> It’s open source, has open source community developing useful plugins,
> such as latest webhelp output

Publican is also open source, so I don't see any benefit to DITA over
DocBook/Publican in that regard. 

Publican has PDF and HTML - it looks like Webhelp is just XHTML with
styling/etc. Is there anything native to webhelp that we don't get from
Publican's HTML output?

We've already put a fair amount of effort into the existing Publican
stuff - so I'd want to see something pretty darn nifty to throw that out
in favor of a new format or have a tool that can easily convert Publican
-> DITA... 

Best, 

Joe
-- 
Joe Brockmeier
jzb@zonker.net
Twitter: @jzb
http://www.dissociatedpress.net/