Mailing-List: contact ooo-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: ooo-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of dave2wave@comcast.net
 designates 76.96.30.56 as permitted sender)
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Apple Message framework v1084)
Subject: Re: DITA for Doc?
From: Dave Fisher <dave2wave@comcast.net>
In-Reply-To: <4E15B09F.6020307@shanecurcuru.org>
Date: Thu, 7 Jul 2011 08:31:59 -0700
Content-Transfer-Encoding: quoted-printable
Message-Id: <C74EFC73-C6A7-4D45-9283-D61663EE72B7@comcast.net>
References: 
 <CAP-ksohK2+nOPwZ1dC9PGev_wL6YinsQnR21pRjDOxEpOWYPmg@mail.gmail.com>
 <CAA4ffp8pzZD2NxJCu3E0DikmPhPdS+Jb00-h=1vzms2+Yf05Ag@mail.gmail.com>
 <4E15ABFF.3000203@gmx.net>
 <CAA4ffp_4ieg8W+TGkzt+yMywpE+eum6fSv3-aRTb2uewkotTrg@mail.gmail.com>
 <4E15B09F.6020307@shanecurcuru.org>
To: ooo-dev@incubator.apache.org


On Jul 7, 2011, at 6:11 AM, Shane Curcuru wrote:

> Yes, that's a good question in terms of who the primary writers of =
this kind of help content are, and if they're participating in this =
thread. But it certainly sounds like there's enough positive feedback =
(and it seems Rob can draw on some experience around DITA) that it's =
definitely worth writing up a more detailed proposal and seeing who's =
willing to start the work.
>=20
> I.e. this is worth putting something linked from the Project Planning =
page, with a sketch of which kinds of documentation are which (i.e. =
product help docs vs. website content vs. user guides), and then a =
proposed project plan of creating a new DITA workflow to generate the =
help docs going forward.  Plus a call to action of committers (or new =
contributors) who would like to work in this space.

+1

> I haven't used DITA much, but I like the idea, and I'm betting there's =
enough experience here to setup a good toolset and workflow.  Plus, if =
we can do this well, it'll be really useful to be able to transform the =
source into all the various different kinds of presentation we'll need.
>=20
> But I'm just a mentor at the moment, so take my technical advice with =
a grain of salt - it's really up to the committers who will be 1) =
writing this doc, and 2) helping to build/maintain the tools to make it =
easy to use and publish.
>=20
> Heck, I wonder if there isn't some way to add-in some processing to =
the CMS to get it to auto-generate the default website, so you can write =
in DITA and get the basic website for free through the CMS.  Then the =
project can have a separate build toolchain that produces product help, =
etc. from the same source.

That's exactly what I am thinking. DITA and the CMS would work together. =
Content could be in both.

The toolkit that Rob pointed to (http://dita-ot.sourceforge.net/ ) uses =
Ant for the workflow. In just a week of playing with the CMS's workflow =
I can see how they can be put together. I will note that the html =
navigation in the docs on that tool are somewhat lame. My thought is =
that the CMS would be used to provide the web look and feel and then =
wrap up the topic and toc elements into a well-designed HTML page.

Regards,
Dave


>=20
> - Shane
>=20
> On 7/7/2011 8:55 AM, Simon Phipps wrote:
>> Absolutely agree, just checking we're not getting ahead of ourselves =
here...
>>=20
>> On Thu, Jul 7, 2011 at 1:52 PM, Mathias Bauer<Mathias_Bauer@gmx.net>  =
wrote:
>>=20
>>> Hi Simon,
>>>=20
>>> that's the question that needs to be answered. So far we just =
discuss
>>> from a technical POV.
>>>=20
>>> Nevertheless it should be seen that currently we have nothing except =
a
>>> home brewn set of macros that never has been used outside of the =
Hamburg
>>> lab (AFAIK). Whoever will be the people to create help content, they
>>> might see DITA as an improvement, because everything is better than
>>> nothing. Frank pointed to some possible problems with existing =
content,
>>> and I for myself see a problem with the help content provider and =
the
>>> existing tool chain, but that could be checked once we will have =
found
>>> out what people want to use.
>>>=20
>>> Regards,
>>> Mathias
>>>=20
>>> On 07.07.2011 12:59, Simon Phipps wrote:
>>>=20
>>>> Is this something that the committers actually planning to do the =
work
>>> want?
>>>> It's not been clear to me which of the voices of this thread are =
among
>>> their
>>>> number.
>>>>=20
>>>> Cheers
>>>>=20
>>>> S.
>>>>=20
>>>>=20
>>>>=20
>>>> On Wed, Jul 6, 2011 at 10:10 PM, Rob Weir<apache@robweir.com>  =
wrote:
>>>>=20
>>>>> Would it be worth considering using DITA for the =
documentation/help?
>>>>>=20
>>>>> 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.
>>>>>=20
>>>>> 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:
>>>>>=20
>>>>> HTML
>>>>> PDF
>>>>> ODT (Open Document Format)
>>>>> Eclipse Help
>>>>> HTML Help
>>>>> Java Help
>>>>> Eclipse Content
>>>>> Word RTF
>>>>> Docbook
>>>>> Troff
>>>>>=20
>>>>> 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.
>>>>>=20
>>>>> 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.
>>>>>=20
>>>>> 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.
>>>>>=20
>>>>> -Rob
>>>>>=20
>>>>=20
>>>>=20
>>>>=20
>>>=20
>>>=20
>>=20
>>=20