Coordination, mentoring, etc

Hello all,

I'm updating the English translation of the Base Handbook from 3.5 to 4.2, and have run across a problem concerning which I'd appreciate some advice and feedback.

In Chapter 3, "Tables," the section following the heading *Creating Tables/Creation using the GUI* begins as follows:

"Database creation using the GUI is described in detail in Chapter 8, "Getting Started with Base," in the /Getting Started with LibreOffice/ book. Therefore only the main sources of error are described here."

The problem is that [the first sentence of] that statement is just plain false.

The GUI offers two ways of creating tables: Use Wizard to Create Table and Create Table in Design View. The /Getting Started/ chapter only provides instructions for using the Wizard. The Wizard only provides database templates with preexisting table and field names. If you want to design a database for any purpose other than the ones that the templates cover, it's useless.

So far as I can tell, there are no instructions provided anywhere in our documentation on how to create a table in Design View, which seems to me to be the method that most users are likely to use. (I could well be wrong about this, but if those instructions exist, they aren't located in the most logical place to look for them.)

Moreover, the /Getting Started/ chapter explains only how to create a flat, single-table database. (I'm not sure why you'd want to do that rather than just use a spreadsheet, but . . . .) The material in the handbook, on the other hand, assumes that you're building a relational database with multiple tables.

The reason I can't just ignore the problem is and go on is: The section that follows this introduction contains some new material in the German that needs to be translated. Translated super-literally, it doesn't make much sense. Good technical instructions are directed at the particular situation in which the user is going to need those instructions and tailored to the user's preexisting knowledge. That context is exactly what the current text doesn't provide, and what I need in order to put this stuff into comprehensible English.

Any and all advice appreciated.

Thanks,
Alan

Hi Alan,

hope I understand most you have written the right way. My
English-knowledge is "very special".

I'm updating the English translation of the Base Handbook from 3.5 to
4.2, and have run across a problem concerning which I'd appreciate some
advice and feedback.

In Chapter 3, "Tables," the section following the heading *Creating
Tables/Creation using the GUI* begins as follows:

"Database creation using the GUI is described in detail in Chapter 8,
"Getting Started with Base," in the /Getting Started with LibreOffice/
book. Therefore only the main sources of error are described here."

The problem is that [the first sentence of] that statement is just plain
false.

I have written most of the Base-Handbuch. The "Getting Started with
Base" in German isn't the same as in English. Could be better to delete
anything which relates to "Getting started ..."

And this is a special problem with most of the content here. Creating a
Database with wizards (incl. queries, forms ...) and creating databases
directly by using the GUI is declared in the German "Getting started
..." This problem will be solved a littel bit with the German
Base-Handbuch 4.3. There is a example added. For the English
Base-handbook it would be better to add the German "Getting-started" as
attachment to the Base-handbook.

Regards

Robert

Hi :slight_smile:
Ahh, i thought this was going to be done by only re-translating the bits
that changed rather than starting from scratch each time? I think starting
from scratch occasionally might be a good idea to make sure everything
really is covered.

Now the question is whether to do the polishing off to Hazel's work on the
4.2, or abandon that or to update her work for the 4.3 and then do the
polishing off after the updating is done.

I thought we had just agreed that the only change between the 4.2 German
Handbook and the 4.3 is the addition of just 1 more full example?
Regards from
Tom :slight_smile:

Hi Tom,

Ahh, i thought this was going to be done by only re-translating the bits
that changed rather than starting from scratch each time? I think starting
from scratch occasionally might be a good idea to make sure everything
really is covered.

Now the question is whether to do the polishing off to Hazel's work on the
4.2, or abandon that or to update her work for the 4.3 and then do the
polishing off after the updating is done.

I thought we had just agreed that the only change between the 4.2 German
Handbook and the 4.3 is the addition of just 1 more full example?

It isn't a problem of the Version 4.2 of Base Handbuch. It's also a
problem of version 4.3 - the links to "Getting started ..." are also in
this version.

I will try to solve this with the next version of the Base Handbuch. I
will put some content of the German "Getting Started" in the
Base-Handbuch and will delete the links to "Getting started".

When I wrote the Base-Handbuch I have never thought it would be
translated and would only be a part of the German documentation. Had
also never thought someone will print a book of it...

Regards

Robert

Option # 1: Write how to create a database using Design view, wizard, and whatever the other mode is;

Option # 2: Include one line stating that it is assumed that the user knows how to do whatever is missing from the documentation, but to which explicit reference is made;

My recommendation is Option # 2.

jonathon

I failed to send this to the list.

I failed to send this to the list.

I failed to send this to the list.

Tom, please pay attention. Alan found a problem with references to the
Englsih Getting Started guide, which he did not realise has changed in
GSv4.2. Starting from scratch translating either the German 4.2 or 4.3
Base Handbook into English would not solve the problem because
references from the Base Handbook to the Getting Started Guide would
still be wrong.

I have just forwarded to the list three notes that I had written
earlier but failed to send as reply to all; instead I replied only to
Alan, so everyone else won't have seen them. In the third I mention
where the previous version of the Getting Started chapter is now
located, renamed as a tutorial.

Robert, does the previous English GS chapter, which is now available
as a tutorial, cover the missing info? If so, Alan can just change the
references from GS to the tutorial. Or we could include that tutorial
in the Handbook as an Appendix; that would work too, perhaps better
than sending people to a separate document. But either of those
solutions depends on whether the tutorial covers the necessary info.

--Jean

Hi Jean,

Robert, does the previous English GS chapter, which is now available
as a tutorial, cover the missing info? If so, Alan can just change the
references from GS to the tutorial. Or we could include that tutorial
in the Handbook as an Appendix; that would work too, perhaps better
than sending people to a separate document. But either of those
solutions depends on whether the tutorial covers the necessary info.

Have downloaded
http://wiki.documentfoundation.org/images/1/13/GS40-GettingStartedLO.pdf.
The Base-chapter is the content, which would be missed in the
Base-handbook (for example: "Creating tables in Design View").
So a link to "Chapter 8 - Getting started with Base" would work also for
Base-Handbook 4.2.

I will find a better solution in the next Base-Handbuch by copying the
missed parts of the German "Getting started ..." into the chapters of
the Base-Handbuch. Haven't seen the Base-Handbuch as a standalone-book.
Thought it was a continuation of "Getting started".

Robert

Whew! I'm afraid it's going to take me a little while to process this whole discussion. Thanks, everyone, for your input.

Alan

Hi :slight_smile:
Yeh, sorry! I thougth we had 2 people working on the Base Handbook and
that 1 of those was duplicating work that has already been done by Hazel
where nothing new has been added since Hazel did her translation.

I didn't realise that redoing work that has already been done was not the
problem and that it was ok to carry on redoing all the rest of the work
that has also already been done.
Regards from
Tom :slight_smile:

Hi :slight_smile:
I think that rather than carry on with the 4.3 it might be better to carry
on from where people have already gotten up to with the 4.2.

Unless translation is really what you want to do in which case finding the
1 chapter that has been added and translating that might be really good.
Regards from
Tom :slight_smile:

Hi Jean, all,

Sorry to not have post before but I was focusing on the LibreOffice
conference and wanted to have time to read the mails of the list.
So I would like to volunteer to coordinating the work on this project.
For those who don't know me, I'm with LibreOffice since the beginning of
the project, I'm working for TDF on a paid basis as release coordinator and
administrative assistant. On my volunteer time, I used to localize the UI
and help of LibreOffice in French, do some QA, and translated some part of
the FAQ from French to English. My English is not good enough to write the
English documentation, but I quite well know all the parts of this project
to be able to help his coordination and help new comers to find their way.

Let me know if you would like me to help on this task :slight_smile:
Kind regards
Sophie

Hello all,

The immediate solution I've adopted is to reference /both/ "GS w/Base" /and/ the online tutorial in the problematic passage in the Handbook. I will post that chapter for review shortly.

As for the long-term issue, there may or may not be one. The question is whether or not we want to keep the English and German documentation in sync, and also if we want to avoid duplication of content in the English documentation.

We're dealing here with 4 documents:

(1)"Getting Started with Base", Chapter 8 in Getting Started with Libreoffice v.3.5
(2)"Einfuehrung in Base," Kapitel 8 in Erste Schritte v.3.3
(3)"Creating a Relational Database using Base" (online tutorial)
(4)"Getting Started with Base" in GS w/LO v.4.2

Items (1),(2), and (3) are all versions of each other; item (4) is substantially different.

Apparently the way this happened is that an early version of GSw/B got translated into German as "Einfuehrung in Base". That German chapter has stayed the same. When GSw/LO was updated from v.4.1 to v.4.2, the bulk of GSw/B was pulled out and made into an online tutorial, and new material was written and inserted as Chapter 8 of the print guide.

The new material contains much more detailed information about how to use the Wizard to create tables than is in the material moved online. Although the online material (item 3) is called a tutorial, the current version of Chapter 8 (GSw/B 4.2) actually seems to me to be more tutorial-like; the steps it offers are more detailed and it includes practice exercises.

If we want to keep the English and the German matching each other, the way to do it would be:
-- take the current English online tutorial "Creating a relational database"
-- restructure it to resemble the Einfuehrung (this wouldn't require much if any original writing, just moving some things around)
-- insert the restructured document into "Getting Started with LibreOffice" as Chapter 8.

We'd then have to decide what to do with the /current/ version of GSw/B (the one that would be getting replaced). One possibility would be to integrate it into the new version. The topics are similar, but integrating it would require a lot of editing.

I don't feel qualified to make a decision on how to proceed. Since Jean was involved in writing GSw/B 4.2 and presumably knows how and why the decision was made to branch the tutorial off from the print guide, perhaps we should wait until she's back and get her input.

(Hope that wasn't too confusing. It sure confuses me.)

Alan

Hello Sophie, all,

Many thanks for offering your help. We have first met in Lyon OOo conference in 2006 and you have been more then a helping hand to me ever since. I think our project and in particular the documentation team will benefit a lot from your help.
As translating the guides into Dutch is my major contribution to our LibreOffice, I cannot but welcome all help that will help us all.

Many thanks again, Sophie and look forward to continue working with you.

Best regards

Hi :slight_smile:

+1

Regards from
Tom :slight_smile:

Hooray for Sophie! Thank you for stepping forward. --Jean

Hi :slight_smile:
Jean has always done a fantastic job at this despite never wanting the job
in the first place. I think she's naturally gifted at it but she also
(obviously!) puts in tons of hard-work at every level.

Top marks for a total star!
Regards from
Tom :slight_smile:

Hi all,

Hooray for Sophie! Thank you for stepping forward. --Jean

Thanks a lot all for your warm welcome on my offer :slight_smile:
Kind regards
Sophie