incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rob Weir <apa...@robweir.com>
Subject Re: DITA for Doc?
Date Thu, 07 Jul 2011 11:52:29 GMT
On Thu, Jul 7, 2011 at 7:26 AM, Mathias Bauer <Mathias_Bauer@gmx.net> wrote:
> Moin,
>
> I know how the help files where written at Sun/Oracle: the writers took
> Writer for the text and used a set of basic macros to put some markup
> into the files. Then they used an xslt to convert the document into the
> xhp format.
>
> I can't speak for the help writers, but most probably that isn't
> necessary as we shouldn't ask those who created help content in the past
> but those who will do it in the future.
>
> IMHO using a well-established, maintained tool instead of a home brewn
> set of macros that probably has lost its maintainer would be a huge
> improvement.
>
> There's another aspect that we should see: extension developers might
> also want to add help content to their extensions. As until now there is
> no tool available for the public, extension developers had a problem.
> DITA would be an improvement for them.
>

That is an interesting idea.  The modularity of DITA should allow a
downstream consumer of AOOo to customize the doc and generate their
own materials relatively easily, using a standard tool set.  For
example, someone could create a Mac-only customized version of AOOo,
add some additional help topics, but then generate doc that omitted
all references to any Windows or Linux specific topics.

I know we've talked about making OOo more modular, componentized, etc.
 Simon, in particular, was suggesting that as a way forward.  With the
help/documentation, we have available an open standard and an Apache
2.0 licensed toolkit that could enable at least that subsystem to be
more modular and in doing so enable new forms of reuse by downstream
consumers.

> ODT export from DITA wouldn't help as it would miss the markup that the
> help content provider needs. So either we had to convert from DITA to
> xhp directly or we had to rewrite the help content provider to support
> the DITA format.
>
> Regards,
> Mathias
>
> On 07.07.2011 00:49, Greg Stein wrote:
>
>> 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