Jean Hollis Weber wrote:
Gary Schnabl wrote:
ghrt wrote:
Gary Schnabl wrote:
ghrt wrote:
I think it will be a good idea to have different folders for
different OOo versions. A guide with some chapters on 2.2 and
others on 2.3.0-dev, with diffs between the software versions, it
will be at least unusable.
Version 2.3, being readily available and being actively pushed for
volunteers to test it, means that it is nearly ready for stable
distribution. Drafting documents for 2.3 should be the norm instead
of writing/editing the documents for a version that will soon be
technically obsolete.
The timeline I found indicates that 2.3 is due for release in September.
Yes, i agree, but i said another thing: to have different folders
for different software versions, ie 2.2, 2.3 and so on. As a
translator, i'm always "a little late" and I might get half a book
with 2.2 and the other half with 2.3. Of course, i took all the
chapters from the beginning with the same version, but mixing them
at oooauthors makes impossible to get latest version on 2.2 since
only 2.3 is on site. That's the idea. Now I think we have diff
folders only for major changes, like 1.x and 2.x.
I agree with ghrt that we need to differentiate things we are
writing/editing for soon-to-be-released versions of OOo from things
written for current (or recently past) versions of OOo.
I agree with Gary that writing/editing for the next version of OOo is
a good idea. However, when we find mistakes (including typos) in
current documents, we should correct them and make those docs as
correct as possible.
A major problem at OOo and OOoAuthors is that the current
documentation is usually quite a bit behind the then-current
implementation. What is passed off as being 2.2 or whatnot is not
really as current as it seems. Any changes in the GUI or new
functions are not always covered, and some elements apparently have
never been covered in the docs or in the online help--especially the
online help.
That is obviously due to a shortage of writers, mostly... Also,
occasionally some of the procedural steps leave holes because they
tend to be incomplete or don't cover all the GUI components or
functions.
All of that is unfortunately quite true. We need lots more people
constantly checking the current docs against the new versions of the
software, to spot new/changed items. Even if those people don't write
about the new/changed stuff, having it flagged would be a great help
to me and the others who do the writing.
Also having various pigeon holes for parking docs for the various
incremental or major versions would necessarily be rather incomplete
and would accomplish little worthwhile, to my way of thinking.
I disagree. Separate the new/revised docs from the currently published
ones until the new version of OOo is released, and then replace the
current docs with the new ones -- and keep the current docs somewhere.
(BTW, I use the "old files" folder for each book for storing drafts
during development, and then periodically delete those copies -- when
I find time to do it. Sounds like a more organised variation on that
technique might be useful.)
I've been concerned for some time that my habit of overwriting
existing docs with new ones is causing problems (or at least
inconvenience) for the translators. Although I've discussed this a bit
with some of the translators, we haven't done anything to improve the
situation for them.
With several people making minor and major corrections to the existing
chapters, "change tracking" can become a real mess if all changes
after initial publication are kept, so comparing old and new chapters
seems to me to be a more workable way of indicating differences. Thus
keeping folders for existing docs vs new/revised docs seems to me to
be a step in the right direction.
I would like to hear from more translators (and anyone else) on this
topic.
--Jean
Hello Jean,
I will start from the translators bit.
The Italian localization team is using a program called OmegaT. With
this program (and I guess also with similar ones, one of the great
advantages is that when an original document is updated, it is
relatively simple to update the translation as OmegaT will show what the
new sentences are.
Regarding tracking the versions in the user guide, I am not sure I see
the need and it creates a big overhead although we may want to consider
it for version 3.
Similarly to what you wrote, what we need in my opinion is a kind of
user guide issuezilla where we could capture:
- "Roadmap" items i.e. improvements made to the program that are not
captured in the user guide. When a version of OOo is released, normally
it comes with a very comprehensive list of what has been added. all we
need to do is for people who are familiar with the contents of the User
guide to check what should be added and create an "issue"
- "bug" items i.e. typos, wrong procedures...
- "Request for enhancement" items, i.e. topics that are not adequately
covered or not covered at all in the user guide.
Lately I have been archiving all the posts to the users list that
concern impress. One day (when I will have time) I will go through them
and see if there is something that should be added to the user guide.
Cheers,
Michele
