You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@openoffice.apache.org by Rob Weir <ap...@robweir.com> on 2011/07/06 23:10:38 UTC
DITA for Doc?
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
Re: DITA for Doc?
Posted by Dave Fisher <da...@comcast.net>.
On Jul 6, 2011, at 4:40 PM, florent andré wrote:
>
>
> On 07/07/2011 01:33 AM, Dave Fisher wrote:
>>
> ...
>>
>> I am currently looking closely at the Apache CMS someone will need to look at the requirements. Where's the best release and what's required?
>
> cms code :
> https://svn.apache.org/repos/infra/websites/cms/
I've been in the build and Joe has done an enhancement I suggested. Allowing adding a class tag - see our people.mdtext.
>
> cms doc :
> http://www.apache.org/dev/cms.html
Sorry, I meant for DITA - as in someone will need to look into its requirements and where to get an appropriate version of the tool.
Regards,
Dave
Re: DITA for Doc?
Posted by florent andré <fl...@4sengines.com>.
On 07/07/2011 01:33 AM, Dave Fisher wrote:
>
...
>
> I am currently looking closely at the Apache CMS someone will need to look at the requirements. Where's the best release and what's required?
cms code :
https://svn.apache.org/repos/infra/websites/cms/
cms doc :
http://www.apache.org/dev/cms.html
Re: DITA for Doc?
Posted by Lee Fisher <bl...@gmail.com>.
> [...] For me examples are best.[...]
Apache Derby uses DITA. AFAIK it's the biggest use of DITA in an open
source project. I wonder if the Derby doc team has any advice for this
new proposal?
http://db.apache.org/derby/manuals/dita.html
http://svn.apache.org/repos/asf/db/derby/docs/trunk/
Re: DITA for Doc?
Posted by Dave Fisher <da...@comcast.net>.
On Jul 6, 2011, at 5:21 PM, Rob Weir wrote:
> On Wed, Jul 6, 2011 at 7:33 PM, Dave Fisher <da...@comcast.net> wrote:
>>
>> On Jul 6, 2011, at 3:55 PM, Rob Weir wrote:
>>
>>> On Wed, Jul 6, 2011 at 6:11 PM, Dave Fisher <da...@comcast.net> wrote:
>>>> Hi Rob,
>>>>
>>>> On Jul 6, 2011, at 2:10 PM, Rob Weir wrote:
>>>>
>>>>> we've already done the work
>>>>> of converting much of the OOo help to DITA.
>>>>
>>>> Is there a software grant coming?
>>>>
>>>
>>> It is worth considering. But I'm not going to face that corporate red
>>> tape merely on speculation that this might be useful. Let's first
>>> discuss whether the DITA approach seems reasonable. I think it is
>>> important for content authors to be aware that this would be writing
>>> documentation with tags, similar to HTML. Good HTML. But this
>>> structure would give us loads of flexibility for how we structure the
>>> content, combine it is different ways, and publish it.
>>>
>>> You can get a flavor of DITA here:
>>>
>>> http://www.xmlmind.com/tutorials/DITA/index.html
>>
>> An example is always helpful. I think that DITA is a reasonable form.
>>
>> The topicref hierarchy is a critical necessity. It is likely as good as
>>
>>> Tags are off-putting to some people who just want to work in a WYSIWYG
>>> fashion, so I wanted to check.
>>
>> I like tags. Where is a complete reference?
>>
>
> DITA is an standard from OASIS (same standards consortium that created
> ODF, though a different committee)
>
> Full specification is here:
> http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.pdf
>
>> It is difficult to repurpose content if is over-fiddled with in a WYSIWYG fashion.
>>
>> Since we want to repurpose this content in many ways this can make sense.
>>
>>> One possible way of working is to
>>> accept raw content in any reasonable format, ODF, DOC, HTML, yellow
>>> crayon on a napkin, etc., and then have a manual cut & paste process
>>> to get that into DITA initially, and then maintain it that way going
>>> forward.
>>
>> I think that we can strive to go back and forth between DITA and markdown. The Apache CMS is easily extensible with XSL. I can see how to structure a transformation.
>>
>
> So the DITA Open Toolkit may be useful here: http://dita-ot.sourceforge.net/
For me examples are best. I find this to be a good approach. Although I am still digesting, I can see that this is a good approach. Heck I can see a docx target as possible as well.
This is not too different from my work document process, really very close.
The question now is how to turn it into an acceptable package for document developers and an svn driven repository. Will this lead to a system that is satisfactory for MediaWiki authors?
More in the days ahead, this is a big meal.
I still think that the openoffice.org main pages will CMS oriented.
Regards,
Dave
>
> It will do DITA to HTML, which at the very least could be used for
> some form of preview in the CMS, before committing changes.
>
> There is also an HTML to DITA converter that might be useful,
> described here: http://dita-ot.sourceforge.net/readme/DITA-h2d.html
>
>
>> How does DITA handle style sheets? Is it easy to have different layout templates for different outputs.
>>
>
> So the unit of document in DITA is a "topic". The topics that
> together are ordered into a document via a "map". This is one level
> of control, the reuse and slice and dicing aspect. Then there is the
> presentation attributes, the styles and classes. That is in the DITA
> Open Toolkit. A good place to start is here:
>
> http://dita-ot.sourceforge.net/readme/DITA-usingtransforms.html
>
> There is additional customization available, but that is the set of
> out-of-the-box parametrized settings.
>
>
>> Is there an ODF to DITA translation?
>>
>
> No. There is pretty much DITA to * conversions, but DITA is at the
> "highest information level" so conversion to any other format results
> in loss of semantic information, while generally gaining presentation
> attributes. ODF is more semi-structured. It should be possible to do
> a constrained conversion of ODF to DITA, but you would need to ensure
> that the author used a specific pre-defined template and religiously
> used only the template styles. Once an author selects text and
> fiddles with the styles to make it 16 pt bold Times New Roman,
> indented 2", then all bets are off.
>
> There are also aspects of DITA that don't quite map to ODF (at least
> without RDF metadata). For example, DITA has an "audience" attribute
> for elements, where you can specify the target audience at a fine
> grained level. Ditto for "platform", "product", "rev", etc. So you
> could have a step in your documentation that is marked as relevant
> only for OOo 3.4.0 beta advanced Linux users. And this information
> could then be published only in a subset of publications. You would
> go crazy trying to emulate this with predefined styles in ODF. It
> would be a combinatorial explosion of styles. With RDF metadata in
> ODF you might have a customized palette of attributes that you could
> apply to text, in addition to the predefined ODF attributes like bold,
> italics, etc. So you would select text and right click and select
> "platform\windows" or "audience\expert", etc. Would be very powerful,
> and is fully supported by ODF 1.2. But OpenOffice doesn't support it
> yet.
>
>
>> I am currently looking closely at the Apache CMS someone will need to look at the requirements. Where's the best release and what's required?
>>
>> Regards,
>> Dave
>>
>>
>>>
>>>> Regards,
>>>> Dave
>>>>
>>
>>
Re: DITA for Doc?
Posted by Rob Weir <ap...@robweir.com>.
On Wed, Jul 6, 2011 at 7:33 PM, Dave Fisher <da...@comcast.net> wrote:
>
> On Jul 6, 2011, at 3:55 PM, Rob Weir wrote:
>
>> On Wed, Jul 6, 2011 at 6:11 PM, Dave Fisher <da...@comcast.net> wrote:
>>> Hi Rob,
>>>
>>> On Jul 6, 2011, at 2:10 PM, Rob Weir wrote:
>>>
>>>> we've already done the work
>>>> of converting much of the OOo help to DITA.
>>>
>>> Is there a software grant coming?
>>>
>>
>> It is worth considering. But I'm not going to face that corporate red
>> tape merely on speculation that this might be useful. Let's first
>> discuss whether the DITA approach seems reasonable. I think it is
>> important for content authors to be aware that this would be writing
>> documentation with tags, similar to HTML. Good HTML. But this
>> structure would give us loads of flexibility for how we structure the
>> content, combine it is different ways, and publish it.
>>
>> You can get a flavor of DITA here:
>>
>> http://www.xmlmind.com/tutorials/DITA/index.html
>
> An example is always helpful. I think that DITA is a reasonable form.
>
> The topicref hierarchy is a critical necessity. It is likely as good as
>
>> Tags are off-putting to some people who just want to work in a WYSIWYG
>> fashion, so I wanted to check.
>
> I like tags. Where is a complete reference?
>
DITA is an standard from OASIS (same standards consortium that created
ODF, though a different committee)
Full specification is here:
http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.pdf
> It is difficult to repurpose content if is over-fiddled with in a WYSIWYG fashion.
>
> Since we want to repurpose this content in many ways this can make sense.
>
>> One possible way of working is to
>> accept raw content in any reasonable format, ODF, DOC, HTML, yellow
>> crayon on a napkin, etc., and then have a manual cut & paste process
>> to get that into DITA initially, and then maintain it that way going
>> forward.
>
> I think that we can strive to go back and forth between DITA and markdown. The Apache CMS is easily extensible with XSL. I can see how to structure a transformation.
>
So the DITA Open Toolkit may be useful here: http://dita-ot.sourceforge.net/
It will do DITA to HTML, which at the very least could be used for
some form of preview in the CMS, before committing changes.
There is also an HTML to DITA converter that might be useful,
described here: http://dita-ot.sourceforge.net/readme/DITA-h2d.html
> How does DITA handle style sheets? Is it easy to have different layout templates for different outputs.
>
So the unit of document in DITA is a "topic". The topics that
together are ordered into a document via a "map". This is one level
of control, the reuse and slice and dicing aspect. Then there is the
presentation attributes, the styles and classes. That is in the DITA
Open Toolkit. A good place to start is here:
http://dita-ot.sourceforge.net/readme/DITA-usingtransforms.html
There is additional customization available, but that is the set of
out-of-the-box parametrized settings.
> Is there an ODF to DITA translation?
>
No. There is pretty much DITA to * conversions, but DITA is at the
"highest information level" so conversion to any other format results
in loss of semantic information, while generally gaining presentation
attributes. ODF is more semi-structured. It should be possible to do
a constrained conversion of ODF to DITA, but you would need to ensure
that the author used a specific pre-defined template and religiously
used only the template styles. Once an author selects text and
fiddles with the styles to make it 16 pt bold Times New Roman,
indented 2", then all bets are off.
There are also aspects of DITA that don't quite map to ODF (at least
without RDF metadata). For example, DITA has an "audience" attribute
for elements, where you can specify the target audience at a fine
grained level. Ditto for "platform", "product", "rev", etc. So you
could have a step in your documentation that is marked as relevant
only for OOo 3.4.0 beta advanced Linux users. And this information
could then be published only in a subset of publications. You would
go crazy trying to emulate this with predefined styles in ODF. It
would be a combinatorial explosion of styles. With RDF metadata in
ODF you might have a customized palette of attributes that you could
apply to text, in addition to the predefined ODF attributes like bold,
italics, etc. So you would select text and right click and select
"platform\windows" or "audience\expert", etc. Would be very powerful,
and is fully supported by ODF 1.2. But OpenOffice doesn't support it
yet.
> I am currently looking closely at the Apache CMS someone will need to look at the requirements. Where's the best release and what's required?
>
> Regards,
> Dave
>
>
>>
>>> Regards,
>>> Dave
>>>
>
>
Re: DITA for Doc?
Posted by Dave Fisher <da...@comcast.net>.
On Jul 6, 2011, at 3:55 PM, Rob Weir wrote:
> On Wed, Jul 6, 2011 at 6:11 PM, Dave Fisher <da...@comcast.net> wrote:
>> Hi Rob,
>>
>> On Jul 6, 2011, at 2:10 PM, Rob Weir wrote:
>>
>>> we've already done the work
>>> of converting much of the OOo help to DITA.
>>
>> Is there a software grant coming?
>>
>
> It is worth considering. But I'm not going to face that corporate red
> tape merely on speculation that this might be useful. Let's first
> discuss whether the DITA approach seems reasonable. I think it is
> important for content authors to be aware that this would be writing
> documentation with tags, similar to HTML. Good HTML. But this
> structure would give us loads of flexibility for how we structure the
> content, combine it is different ways, and publish it.
>
> You can get a flavor of DITA here:
>
> http://www.xmlmind.com/tutorials/DITA/index.html
An example is always helpful. I think that DITA is a reasonable form.
The topicref hierarchy is a critical necessity. It is likely as good as
> Tags are off-putting to some people who just want to work in a WYSIWYG
> fashion, so I wanted to check.
I like tags. Where is a complete reference?
It is difficult to repurpose content if is over-fiddled with in a WYSIWYG fashion.
Since we want to repurpose this content in many ways this can make sense.
> One possible way of working is to
> accept raw content in any reasonable format, ODF, DOC, HTML, yellow
> crayon on a napkin, etc., and then have a manual cut & paste process
> to get that into DITA initially, and then maintain it that way going
> forward.
I think that we can strive to go back and forth between DITA and markdown. The Apache CMS is easily extensible with XSL. I can see how to structure a transformation.
How does DITA handle style sheets? Is it easy to have different layout templates for different outputs.
Is there an ODF to DITA translation?
I am currently looking closely at the Apache CMS someone will need to look at the requirements. Where's the best release and what's required?
Regards,
Dave
>
>> Regards,
>> Dave
>>
Re: DITA for Doc?
Posted by Rob Weir <ap...@robweir.com>.
On Wed, Jul 6, 2011 at 6:11 PM, Dave Fisher <da...@comcast.net> wrote:
> Hi Rob,
>
> On Jul 6, 2011, at 2:10 PM, Rob Weir wrote:
>
>> we've already done the work
>> of converting much of the OOo help to DITA.
>
> Is there a software grant coming?
>
It is worth considering. But I'm not going to face that corporate red
tape merely on speculation that this might be useful. Let's first
discuss whether the DITA approach seems reasonable. I think it is
important for content authors to be aware that this would be writing
documentation with tags, similar to HTML. Good HTML. But this
structure would give us loads of flexibility for how we structure the
content, combine it is different ways, and publish it.
You can get a flavor of DITA here:
http://www.xmlmind.com/tutorials/DITA/index.html
Tags are off-putting to some people who just want to work in a WYSIWYG
fashion, so I wanted to check. One possible way of working is to
accept raw content in any reasonable format, ODF, DOC, HTML, yellow
crayon on a napkin, etc., and then have a manual cut & paste process
to get that into DITA initially, and then maintain it that way going
forward.
> Regards,
> Dave
>
Re: DITA for Doc?
Posted by Dave Fisher <da...@comcast.net>.
Hi Rob,
On Jul 6, 2011, at 2:10 PM, Rob Weir wrote:
> we've already done the work
> of converting much of the OOo help to DITA.
Is there a software grant coming?
Regards,
Dave
Re: DITA for Doc?
Posted by Andy Brown <an...@the-martin-byrd.net>.
Greg Stein 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
Your correct. The current group working on the documents use OOo to
write/edit the manuals. Using anything else will stand the chance of
running those people off. Other means for the developer material is
open as that side was not done in ODF to start with.
Andy
Re: DITA for Doc?
Posted by Graham Lauder <yo...@openoffice.org>.
On Thu, 2011-07-07 at 07:52 -0400, Rob Weir wrote:
> On Thu, Jul 7, 2011 at 7:26 AM, Mathias Bauer <Ma...@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.
More importantly, Community Members could contribute patches to the help
documentation which could then be easily adopted. The help has been one
component that has needed some more love for sometime. It was hard to
drum up interest, if DITA were a way to lower some barriers, then
great.
--
Graham Lauder,
OpenOffice.org MarCon (Marketing Contact) NZ
http://marketing.openoffice.org/contacts.html
OpenOffice.org Migration and training Consultant.
Re: DITA for Doc?
Posted by Rob Weir <ap...@robweir.com>.
On Thu, Jul 7, 2011 at 7:26 AM, Mathias Bauer <Ma...@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 <ap...@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 <gs...@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 <ap...@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
>>>>>
>>>>
>>>
>>
>
>
Re: DITA for Doc?
Posted by Mathias Bauer <Ma...@gmx.net>.
On 07.07.2011 18:52, Pedro F. Giffuni wrote:
>
>
> --- On Thu, 7/7/11, Mathias Bauer <Ma...@gmx.net> wrote:
>
> ...
>>
>> The macro package is available as an extension that can be
>> installed with the extension manager. It also contains the
>> xslt that is installed as an export filter.
>>
>
> Just wondering ..
>
> Is this where we use saxon?
IIRC yes.
Regards,
Mathias
Re: DITA for Doc?
Posted by Rob Weir <ap...@robweir.com>.
On Sat, Jul 9, 2011 at 3:55 PM, Pedro F. Giffuni <gi...@tutopia.com> wrote:
> Hi Rob:
>
> Would the idea be to include the DITA Open Toolkit in
> OpenOffice or to keep it as an external package?
>
It would be a build-time dependency, used when generating doc files.
It would not a run-time dependency for the user.
> I downloaded the minimal DITA Open Toolkit to explore
> how to package it for FreeBSD, and it seems like it is
> meant to be embedded into bigger applications, it
> also includes some other stuff, in particular saxon
> (MPL).
>
> cheers,
>
> Pedro.
>
>
>
>
>
Re: DITA for Doc?
Posted by "Pedro F. Giffuni" <gi...@tutopia.com>.
Hi Rob:
Would the idea be to include the DITA Open Toolkit in
OpenOffice or to keep it as an external package?
I downloaded the minimal DITA Open Toolkit to explore
how to package it for FreeBSD, and it seems like it is
meant to be embedded into bigger applications, it
also includes some other stuff, in particular saxon
(MPL).
cheers,
Pedro.
Re: DITA for Doc?
Posted by "Pedro F. Giffuni" <gi...@tutopia.com>.
--- On Thu, 7/7/11, Mathias Bauer <Ma...@gmx.net> wrote:
...
>
> The macro package is available as an extension that can be
> installed with the extension manager. It also contains the
> xslt that is installed as an export filter.
>
Just wondering ..
Is this where we use saxon? AFAICT, it's not a problem
license-wise, (MPL with a commercial version available but
it is not a run dependency) but it would be good to get
rid of it.
Pedro.
> I only rarely worked with this help editor, but from these
> occasions I
> remember that it was a little bit awkward.
>
> > Mathias, you would know much better than I how
> feasible it would be to
> > use some kind of Writer window to display help.
> Without making light of
> > the technical problems, I am intrigued by lowering the
> participation bar
> > that far. Translators could work directly with .odt
> files. Users could
> > customize their own help, using Writer, and (we would
> hope) send us
> > their suggestions and improvements.
>
> You might think that using Writer to edit the help content
> is a big
> plus, but all that is used is entering text and formatting
> through the
> assignment of styles - nothing fancy, as the help content
> file format
> itself isn't very feature rich. So the learning curve for
> other editors
> should be quite flat.
>
> Anyway, I don't believe that this is one of the most urgent
> problems to
> solve. First we have to get the code and build it, later we
> can look for
> people willing to write help content. We should present
> them the
> alternatives (and something like DITA definitely would be
> one to
> consider) and ask them what they prefer.
>
> Regards,
> Mathias
>
>
Re: DITA for Doc?
Posted by Mathias Bauer <Ma...@gmx.net>.
On 07.07.2011 14:59, TJ Frazier wrote:
> On 7/7/2011 07:26, Mathias Bauer 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.
>
> While I don't oppose a change to DITA, I do offer another string to the
> bow. One advantage of the Writer / macros method is that it greatly
> lowers the bar to participation. Example: I volunteer to maintain the
> macros (and at least help with the source) either for the interim, or
> indefinitely. I don't know xslt technology, but I should be able to
> learn as much as is needed, quickly.
>>
>> 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.
>
> The obvious alternative is to make the existing method public: create a
> template with the Basic macros in a library, and make that and the xslt
> down-loadable.
The macro package is available as an extension that can be installed
with the extenion manager. It also contains the xslt that is installed
as an export filter.
I only rarely worked with this help editor, but from these occasions I
remember that it was a little bit awkward.
> Mathias, you would know much better than I how feasible it would be to
> use some kind of Writer window to display help. Without making light of
> the technical problems, I am intrigued by lowering the participation bar
> that far. Translators could work directly with .odt files. Users could
> customize their own help, using Writer, and (we would hope) send us
> their suggestions and improvements.
You might think that using Writer to edit the help content is a big
plus, but all that is used is entering text and formatting through the
assignment of styles - nothing fancy, as the help content file format
itself isn't very feature rich. So the learning curve for other editors
should be quite flat.
Anyway, I don't believe that this is one of the most urgent problems to
solve. First we have to get the code and build it, later we can look for
people willing to write help content. We should present them the
alternatives (and something like DITA definitely would be one to
consider) and ask them what they prefer.
Regards,
Mathias
Re: DITA for Doc?
Posted by TJ Frazier <tj...@cfl.rr.com>.
On 7/7/2011 07:26, Mathias Bauer 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.
While I don't oppose a change to DITA, I do offer another string to the
bow. One advantage of the Writer / macros method is that it greatly
lowers the bar to participation. Example: I volunteer to maintain the
macros (and at least help with the source) either for the interim, or
indefinitely. I don't know xslt technology, but I should be able to
learn as much as is needed, quickly.
>
> 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.
The obvious alternative is to make the existing method public: create a
template with the Basic macros in a library, and make that and the xslt
down-loadable.
>
> 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.
Re-doing the help content provider is IMHO an excellent idea. Again,
there are two ways to go: a DITA provider, or an ODF (actually, .odt)
provider.
Mathias, you would know much better than I how feasible it would be to
use some kind of Writer window to display help. Without making light of
the technical problems, I am intrigued by lowering the participation bar
that far. Translators could work directly with .odt files. Users could
customize their own help, using Writer, and (we would hope) send us
their suggestions and improvements.
HTH. --/tj/
>
> 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<ap...@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<gs...@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<ap...@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
>>>>>
>>>>
>>>
>>
>
>
>
Re: DITA for Doc?
Posted by Mathias Bauer <Ma...@gmx.net>.
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.
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 <ap...@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 <gs...@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 <ap...@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
>>>>
>>>
>>
>
Re: DITA for Doc?
Posted by Greg Stein <gs...@gmail.com>.
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 <ap...@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 <gs...@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 <ap...@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
>>>
>>
>
Re: DITA for Doc?
Posted by Rob Weir <ap...@robweir.com>.
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 <gs...@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 <ap...@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
>>
>
Re: DITA for Doc?
Posted by Greg Stein <gs...@gmail.com>.
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 <ap...@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
>
Re: DITA for Doc?
Posted by Dave Fisher <da...@comcast.net>.
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<Ma...@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<ap...@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
>>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>
>>
Re: DITA for Doc?
Posted by Shane Curcuru <as...@shanecurcuru.org>.
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.
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.
- 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<Ma...@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<ap...@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
>>>>
>>>
>>>
>>>
>>
>>
>
>
Re: DITA for Doc?
Posted by Simon Phipps <si...@webmink.com>.
Absolutely agree, just checking we're not getting ahead of ourselves here...
On Thu, Jul 7, 2011 at 1:52 PM, Mathias Bauer <Ma...@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 <ap...@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
> >>
> >
> >
> >
>
>
--
Simon Phipps
+1 415 683 7660 : www.webmink.com
Re: DITA for Doc?
Posted by Mathias Bauer <Ma...@gmx.net>.
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 <ap...@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
>>
>
>
>
Re: DITA for Doc?
Posted by Simon Phipps <si...@webmink.com>.
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 <ap...@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
>
--
Simon Phipps
+1 415 683 7660 : www.webmink.com
Re: DITA for Doc?
Posted by Rob Weir <ap...@robweir.com>.
On Thu, Jul 7, 2011 at 6:50 AM, Frank Peters <fp...@googlemail.com> wrote:
> Rob,
>
> Would it be worth considering using DITA for the documentation/help?
>
> [...]
>
>> 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.
>
> What a coincidence <eg> So the Symphony team will contribute their
> work back to AOOo? I would suggest to talk to localizers to prevent
> flushing their work down the drain when migrating.
>
Not exactly a coincidence. IBM invented DITA. We contributed it to
OASIS. Today is it used broadly for technical documentation, as the
industry standard. Take a look at the list here:
http://dita.xml.org/book/list-of-organizations-using-dita
> Does the DITA implementation of Symphony support all functions
> that OOo help currently offers, e.g. context-sensitivity,
> extended tips, text transclusion, etc?
>
DITA has transclusion, yes. But it is "type-safe". So you cannot
just suck in any fragment from one place into another place. It is
needs to be compatible. So error checking can be done via XML
validation, catching errors more easily and earlier.
Context-sensitivity is more a runtime behavior , something that runs
against the published output. But you can certainly encode help
context ID's in the DITA source.
We use DITA in Symphony for almost everything: integrated editor help,
tutorials, demo scripts, toolbar/keyboard reference cards and
developer guide.
> When we switched the format of SO/OOo back then, it was a major
> hassle to include all localizations in the migration. Beware of
> any side-effects.
>
Yes.
> Frank
>
>
Re: DITA for Doc?
Posted by Frank Peters <fp...@googlemail.com>.
Rob,
Would it be worth considering using DITA for the documentation/help?
[...]
> 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.
What a coincidence <eg> So the Symphony team will contribute their
work back to AOOo? I would suggest to talk to localizers to prevent
flushing their work down the drain when migrating.
Does the DITA implementation of Symphony support all functions
that OOo help currently offers, e.g. context-sensitivity,
extended tips, text transclusion, etc?
When we switched the format of SO/OOo back then, it was a major
hassle to include all localizations in the migration. Beware of
any side-effects.
Frank
Re: DITA for Doc?
Posted by Wolf Halton <wo...@gmail.com>.
+1
Since off is
On Jul 6, 2011 5:11 PM, "Rob Weir" <ap...@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
Re: DITA for Doc?
Posted by Rob Weir <ap...@robweir.com>.
On Wed, Jul 6, 2011 at 6:09 PM, Dave Fisher <da...@comcast.net> wrote:
> Rob,
>
> I am surprised that you did not suggest using the ODF Toolkit.
>
The DITA Open Toolkit already supports ODF output. They did this back
in early 2010 using a XSLT transform. Although I think doing it with
the ODF Toolkit would be infinitely more elegant, poetic and majestic,
and might even run faster, my belief in that is not so great as to
offer to rewrite it for them. Maybe someday.
Remember, DITA is not just a word processor format. It is a
structured, modular vocabulary for technical documentation. Although
there are dedicated authoring tools, you can author DITA in any XML
editor, or even a text editor.
Now, you could certainly build DITA-like behavior on top of an
OpenOffice, using the RDF XML/RDFa semantic metadata extensibility
features of ODF 1.2, I have not seen any ODF word processor implement
this to the extent that would be needed. It could also be enabled via
plugins or macros, as has been done with some 3rd party DITA apps for
MS Word.
But then I think you would want to compare a standards-based approach
to technical doc, that is supported by a broad ecosystem of tools,
versus an ad-hoc one used by only us.
> Dave
>
> On Jul 6, 2011, at 2:10 PM, Rob Weir 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
>
>
Re: DITA for Doc?
Posted by Dave Fisher <da...@comcast.net>.
Rob,
I am surprised that you did not suggest using the ODF Toolkit.
Regards,
Dave
On Jul 6, 2011, at 2:10 PM, Rob Weir 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
Re: DITA for Doc?
Posted by florent andré <fl...@4sengines.com>.
Hi there,
I'm +1 with this proposal, DITA is a great concept for technical
documentation in a technical environment (diff, commits, factorisation
of documentation, etc...).
Each tool has his target, client, ... AOoO is a good think for a kind of
target, DITA for another.
... And maven has a plugin [1], that "In addition, it also has extra
goals to [...] configure Eclipse IDE to allow editing and building DITA."
++
[1] http://mojo.codehaus.org/dita-maven-plugin/
(not tested)
On 07/06/2011 11:10 PM, Rob Weir 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
Re: DITA for Doc?
Posted by Wolf Halton <wo...@gmail.com>.
Since odf is one of their outputs already...
On Jul 6, 2011 5:11 PM, "Rob Weir" <ap...@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