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 Source format for user guides
Date Sun, 26 Jun 2011 23:32:51 GMT
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