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:07:23 GMT
Oh, one other thing.  Are we set with translation management software
that works with ODF?

-Rob

On Sun, Jun 26, 2011 at 8:00 PM, Rob Weir <apache@robweir.com> wrote:
> 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