incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jean Hollis Weber <jeanwe...@gmail.com>
Subject Re: Source format for user guides
Date Mon, 27 Jun 2011 00:47:39 GMT
On Sun, 2011-06-26 at 20:00 -0400, Rob Weir wrote: 
> I like the idea of using ODF, for the reasons you state.
> 
> I assuming this implies ODF files in the SVN repository. 

Why? I'm sure I saw a note earlier on this list that user docs don't
need to be in SVN, and I certainly do not see this is necessary. 

The user guides are not part of the product, nor are they shipped with
the product (except some CDs/DVDs include the PDFs, I believe).

If it is necessary, only the published chapters and books should be put
into SVN... not drafts as they are developed. 

BTW, books are published as individual chapters (typically 20-40 pages,
but sometimes longer), then compiled into complete books (typically
250-450 pages).

I was going to write a separate note about continuing to use the
ODFAuthors website for production (drafts, reviewing, etc), with
published docs made available through the wiki... but I'll mentioned
this briefly here. 

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.

--Jean 

> If so, we're
> going to have three pain points:
> 
> 1) Since ODF is not a text format, diff's are not possible with the
> default SVN tools.  Yes, we can do change tracking inside of the
> document, but it is harder to monitor changes to an ODF document in
> the repository by looking at commit messages.
> 
> 2) How do non-committer contributors submit user guide patches and how
> are they reviewed and applied?
> 
> 3) Similar to #2, how do we merge changes if multiple committers
> modify the same file?
> 
> None of these are killers.  We could reduce the the impact of #3 if we
> used fine-grained ODF documents.  So instead of 100 page documents,
> have ten ten-page documents that could be merged for publication.
> That way we get fewer conflicts.
> 
> There are things we could do about #1.  SVN allows an external diff
> program.  We could write one, perhaps using the ODF Toolkit, that
> extracts text and diffs it.  Similarly, we could write an ODF patch
> utility.  Yes, this is extra work, but it is useful and would benefit
> more than just OOo.
> 
> -Rob






Mime
View raw message