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
