incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Fisher <dave2w...@comcast.net>
Subject Re: DITA for Doc?
Date Thu, 07 Jul 2011 15:31:59 GMT

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.
> 
> 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.
> 
> 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.
> 
> 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


> 
> - Shane
> 
> On 7/7/2011 8:55 AM, Simon Phipps wrote:
>> Absolutely agree, just checking we're not getting ahead of ourselves here...
>> 
>> On Thu, Jul 7, 2011 at 1:52 PM, Mathias Bauer<Mathias_Bauer@gmx.net>  wrote:
>> 
>>> Hi Simon,
>>> 
>>> that's the question that needs to be answered. So far we just discuss
>>> from a technical POV.
>>> 
>>> 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.
>>> 
>>> Regards,
>>> Mathias
>>> 
>>> On 07.07.2011 12:59, Simon Phipps wrote:
>>> 
>>>> 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.
>>>> 
>>>> Cheers
>>>> 
>>>> S.
>>>> 
>>>> 
>>>> 
>>>> On Wed, Jul 6, 2011 at 10:10 PM, 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