I like the idea of using ODF, for the reasons you state. I assuming this implies ODF files in the SVN repository. 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 On Sun, Jun 26, 2011 at 7:32 PM, Jean Hollis Weber <jeanwe...@gmail.com> wrote: > The topic of this note is USER GUIDES, one of several possible types of > user documentation. What I say here is not necessarily relevant to other > types of user doc. > > I assume that user guides similar to the existing ones are a desirable > subset of user documentation, and that we wish to continue producing > them. > > Therefore, I propose that we agree the SOURCE FORMAT for the USER GUIDES > will continue to be ODT. (The alternative is wiki format for the > source.) > > Reasons: > 1) Writing documentation for an office suite using any method other than > the office suite itself strikes me as a very bad advertisement for one's > product. > > 2) ODT source enables us to publish guides in numerous formats > relatively quickly and easily. This is what we're doing now. From wiki > format, conversion to ODT and PDF (and other formats?) is possible but > the results need a lot of manual tweaking to be of high standard. > > 3) Using ODT files as source enables people to work on the user guides > without needing to have Internet access while doing the work. > > 4) Tracking changes during edit and review is easy using OOo's change > tracking tools. Wiki "change tracking" is cumbersome and AFAIK one > cannot accept or reject individual changed items; one can only revert a > set of changes or re-edit the revision. > > 5) For these reasons, the people who have been producing the OOo user > guides over the years have expressed a clear preference for working in > ODT, not wiki. > > --Jean > >
