incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dennis E. Hamilton" <>
Subject RE: Source format for user guides
Date Mon, 27 Jun 2011 20:33:48 GMT
Two observations:

 1. I don't think the PMC has much to do with it if you author outside of  I think
you're then likely to be publishing outside of the project too.
 That doesn't mean they can't be loosely coupled, I just think it is too late to come around
to the project with finished documents of unmanaged provenance.  (The wrinkle is material
that is included in the basic software distro, such as integrated help in its myriad translations.)

 2. If we are going to take the step of going to a non-* (i.e., non-ODF interchanged)
authoring form in an editable text, whether DocBook XML, LaTeX, troff, whatever, there is
no reason not to put the other foot in the fire and integrate with the Apache production model
and SVN version control.  It doesn't matter what front-end an author might use so long as
it is understood that the authoring form is one of those.

I'm not offering an opinion because I don't have enough skin in this part of the game.  My
sense is that there is some concern for avoiding (2) so that authors are quickly accommodated
in a way where they are already fluent have a process with which they are comfortable.

For me, having a DocBook authoring and production tool chain is as much mystery meat as is
 web authoring via Markdown and an SVN-anchored production tool chain.  But I am not on the
critical path as a contributor to either.

Just sayin'

 - Dennis

-----Original Message-----
From: Frank Peters [] 
Sent: Monday, June 27, 2011 11:21
Subject: Re: Source format for user guides

[ ... ]

[From Jean:]
> Rob,
> No. None of the above is the intent. ODFAuthors is, and intends to
> remain, independent. Some variation on our existing workflow and
> procedures could certainly be accommodated. For example, OOo-related
> discussion could be carried out on a mailing list at Apache instead of
> on the existing list at OOo (or the ODFAuthors list), and "release
> candidates" of user guide chapters could be approved by the PMC.

So basically, like with the OOo Docs Project, ODFAuthors remains
independent and Apache OOo can take advantage of the material by
publishing it on the website and/or the wiki, much like what happens
today at (classical) OOo.

and in another post of Jean:

> BTW, OOoAuthors (the precursor to ODFAuthors) was set up largely because
> of the difficulty of user documentation producers in coping with the
> sort of versioning and tracking systems used by code developers.

Source code management systems in general are only poorly suited to
work with documentation, unless you *stricly* separate
content from representation. You could then make the latter part of
the documentation build process, where the content is compiled into
ODF/PDF/HTML/Whatever using certain styles and templates.

[ ... ]

We could go for Docbook (or a simplified Doc book), for example,
or XHTML. Or even flat-ODF (uncompressed XML stream), although this
stream is fairly "polluted" with insignificant meta information
and would therefore be harder to "normalize" for SVN storage.

An advantage of this approach would be that we can showcase
OOo's excellent potential as "generic" authoring tool through
filters to almost any XML-based format.


View raw message