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<[email protected]> 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<[email protected]> 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
