incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rob Weir <apa...@robweir.com>
Subject Re: Source format for user guides
Date Mon, 27 Jun 2011 00:00:33 GMT
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 <jeanweber@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
>
>

Mime
View raw message