incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Greg Stein <gst...@gmail.com>
Subject Re: DITA for Doc?
Date Wed, 06 Jul 2011 22:49:39 GMT
Ah. User guides vs $otherstuff.

For developer documentation, I'd be partial to doxygen. For help
doc... no opinion.

Cheers,
-g

On Wed, Jul 6, 2011 at 18:08, Rob Weir <apache@robweir.com> wrote:
> That was user guides.  I'm talking about help documentation, though
> the DITA approach could certainly handle user guides with ease as
> well.
>
> And remember, there is more than one doc team to consider here.  And
> once of them would like to use DITA.
>
> -Rob
>
> On Wed, Jul 6, 2011 at 5:46 PM, Greg Stein <gstein@gmail.com> wrote:
>> I seem to recall an email from the doc people that they wanted to
>> stick to their current toolset and infrastructure, rather than bring
>> that to the ASF. My take-away from that message is that the OOo
>> documentation is written by other/downstream people, rather than as a
>> deliverable from the ASF.
>>
>> Cheers,
>> -g
>>
>> On Wed, Jul 6, 2011 at 17:10, Rob Weir <apache@robweir.com> wrote:
>>> Would it be worth considering using DITA for the documentation/help?
>>>
>>> I love ODF as much as anyone, but DITA was designed specifically for
>>> technical documentation, and has built-in facilities for making
>>> modular "topics" that then can be reassembled, with a "map" to
>>> assemble larger works.  This gives you the ability, for example, to
>>> have paragraph that only shows up in the Linux version of the doc, but
>>> not in the Windows version.
>>>
>>> You also get an easy ability, via the DITA Open Toolkit (which is
>>> Apache 2.0 licensed), to transform the DITA source into a large
>>> variety of output forms, including:
>>>
>>> HTML
>>> PDF
>>> ODT (Open Document Format)
>>> Eclipse Help
>>> HTML Help
>>> Java Help
>>> Eclipse Content
>>> Word RTF
>>> Docbook
>>> Troff
>>>
>>> The authors focus on the structure and content, and the layout and
>>> styling is deferred until publication time.  So you have a great deal
>>> of flexibility for targeting the same content to various uses.
>>>
>>> The other nice thing is that DITA is text (well, XML specifically), so
>>> we use SVN to manage the content, can do diff's, merges, use the
>>> editor of our choice, etc.
>>>
>>> I'd like to argue for the advantages of DITA as a source format here.
>>> I can probably find some volunteers to help enabled this.  The
>>> Symphony team uses DITA for doc/help, and we've already done the work
>>> of converting much of the OOo help to DITA.
>>>
>>> -Rob
>>>
>>
>

Mime
View raw message