Updating the Base Guide

Documentation General
#1

Hello everybody.

During the past few weeks, I have become more familiar with Base and the Base Guide (BG). In summary, I feel that the content of the BG would benefit from some care and attention. This will be time consuming and should be considered as a long-term aim, not a short-term fix.

I think we should adopt a phased approach to improving the document rather than trying to overhaul it all at once.

I suggest that we try to create an update to be published as soon as possible after the release of LO 7.3. The following improvements would be worthwhile and should be achievable in that time frame:

1. Review and update Chapter 1, Introduction to Base, so that is better
    aligned with the guides for other LO components and provides more
    information aimed at novice users. (A draft update will be available
    for review in a few days)
2. Update two of the sample databases that are publicly available
    (Media_without_Macros.odb and Example_Sport.odb) so that they are
    consistent with the revised text of Chapter 1.
3. Review and update Chapter 2, Creating a Database (task includes
    refreshing and anglicizing figures where necessary, and checking
    correctness of text). I will work on this as soon as I’ve completed
    the Chapter 1 update.
4. Update all other chapters to add captions to the many figures that
    do not currently have them.
5. Update all other chapters to remove any unnecessary negativity about
    the software product.

Does the above sound reasonable for the first step in a phased update plan?

Regards,

Steve

#2

Flagging https://wiki.documentfoundation.org/images/d/d5/Automobile.odb for
a maintenance update. iirc fuel usage table records are all identical and
need to be varied. It's used in
https://ask.libreoffice.org/t/scriptforge-database-demo/69155 which is
intended to be located in the wiki. I'll provide details in the new year.

#3

Hi Steve,

I have a comment on Chapter 2, Creating a Database:
In the part on PostgreSQL some instructions is written to use PostgreSQL in Linux/OpenSUSE. As the majority of LibreOffice users are using Windows, should be there an instruction aimed at Windows users?

Throughout the Guide Linux is used... (also in the figures). all manuals have Windows based figures, why not use windows figured here as well?

best regards,

Rob Westein

#4

Hi Rob,

I have a comment on Chapter 2, Creating a Database:
In the part on PostgreSQL some instructions is written to use PostgreSQL in Linux/OpenSUSE. As the majority of LibreOffice users are using Windows, should be there an instruction aimed at Windows users?

Reason here: I am the author of most content of the original Base Handbuch (Germany). And I'm using OpenSUSE since 20 years. Couldn't test anything in Windows.

Throughout the Guide Linux is used... (also in the figures). all manuals have Windows based figures, why not use windows figured here as well?

Same reason as above. We had discussions here about screenshots and decided to create all screenshots in Linux with a special theme. We won't show the behavior of open source software with screenshots of closed source software. Could also be a special problems with the right to use this screenshots in a published book.

Regards

Robert

#5

Hi Rob and Robert.

Thanks for passing on your thoughts.

There seem to be two issues here.

1. With regards to the figures throughout the Base Guide, any that I
    replace will be captured in a Windows environment. As often happens,
    the book will then contain figures from a mixture of environments
    but we can't do much about that in the short term.
2. With regards to the (text) instructions, then I will be working
    through the book following those instructions on my Windows
    computer. Where the instructions don't work on Windows, then I'll
    try and work out why there's a difference. If the answer is obvious
    then all well and good; if not, then I'll follow up with a mailing
    list question to seek guidance.

Regards,

Steve

#6

I've checked Base Guide 7.2 and the Automobile.odb database is not used.

Base Guide comments:

   1. One of the regular contributors on ask.libreoffice.org explained
   something like Base is a holder document for a database, a concept that
   would sit well in the guide
   2. Example databases are generally much more complex than required for
   what they aim to demonstrate
   3. Would be a good opportunity to introduce the open source example
   https://github.com/lerocha/chinook-database often used as a northwind
   alternative

#7

Hi flywire,

I've checked Base Guide 7.2 and the Automobile.odb database is not used.

Automobile.odb isn't an example database for the Base Guide. It is used for Base chapter in Getting Started Guide.

There are many other databases for the Base Guide. Media_without_Macros.odb" and "Media_with_Macros.odb" are the central databases, which will show a real working database for libraries. And all the other little examples I have created for little special problems. So everybody could read about the code in the Guide and could test it in the database.
The current German version of Base Handbuch 7.2 is published together with 22 Database …

… but: The English version will never be translated from the German version again. The first English version has been created this way, because the German version still exists.

Regards

Robert

#8

Thanks Robert. I've worked through a lot of LO documentation over the last
year and I can't always remember what was where. Some more comments:

   1. It seems I've failed to understand the Automobile database use case
   then misunderstood the Fuel table use (which I understood was like a
   personal vehicle log book). It's not clear to me what is being planned for.
   I understand the Automobile database is a personal database to track
   holiday expenses within a group. With over 16,000 words plus figures in
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase.html#toc6
   it's hard to pick up on detail when you're familiar with most of it. Can
   you explain Figure 35
   <https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase-img/GS7208-GettingStartedWithBase-img036.png>
   in a sentence? Specifically:
      1. Why refuel a vehicle multiple times each day?
      2. Why would the vehicle odometer be close to zero rather than
      something more typical of vehicles on the road?
      3. Why are so many different people paying for fuel?
   2. Using one definitive document is best to avoid inconsistencies. Is
   the GS Guide consistent with
   https://wiki.documentfoundation.org/images/d/d5/Automobile.odb ?
   3. Re the 22 databases. Are you suggesting the base guide should work
   towards a single database to demonstrate Base functionality rather than
   many databases (say like northwind.mdb)?
   4. Duplicating a database with the exception of macros so users aren't
   exposed to macros seems crazy. Rather than having two identical
   databases with the exception of macros, perhaps just merge a macro file
   into the database?

#9

Hi flywire,

I haven't created anything of the "Getting started with Base" and don't know anything about the database Automobile.odb. (Never had a car here, ride a bike for short distances and go by train for long distances.)

    3. Re the 22 databases. Are you suggesting the base guide should work
    towards a single database to demonstrate Base functionality rather than
    many databases (say like northwind.mdb)?

First there has been the "Media.odb" for the whole content. But the content couldn't touch all problems. So there are special databases, for example, for creating charts in a form, for saving data like arrays in the internal HSQLDB …

    4. Duplicating a database with the exception of macros so users aren't
    exposed to macros seems crazy. Rather than having two identical
    databases with the exception of macros, perhaps just merge a macro file
    into the database?

No, the first database a user creates won't contain any macros. So I created "Media_without_Macros.odb" first. This database will work and show all the possibilities given without needing any special code except SQL.

Macros are an addon for any database. So I have looked for those parts in the first created database, which would make it easier to work with the database. The forms, for example would be created in a different way. In one form there are many Listboxes for adding content to different tables. The same form in "Media_with_Macros.odb" will create the content for other tables by filling it in the "Listboxes" (Combobox with macro → looks for content in the table and inserts primarykey).

None of this should hold you back from rewriting the content. The Geman Base Handbuch isn't the same as the Base Guide for many versions. But if there is anybody who will create new database many content must be changed in the Englisch Base Guide.

Regards

Robert

#10

IIRC, the Automobile database was created by Dan Lewis to use in classes
he was teaching. I haven’t seen him around for a while. I can try to answer
some of your questions.

   1. It seems I've failed to understand the Automobile database use case
   then misunderstood the Fuel table use (which I understood was like a
   personal vehicle log book). It's not clear to me what is being planned
for.
   I understand the Automobile database is a personal database to track
   holiday expenses within a group. With over 16,000 words plus figures in

https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase.html#toc6
   it's hard to pick up on detail when you're familiar with most of it. Can
   you explain Figure 35
   <
https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase-img/GS7208-GettingStartedWithBase-img036.png
>
   in a sentence? Specifically:
      1. Why refuel a vehicle multiple times each day?

The USA (where Dan lives) and Australia (where I live) are as large as all
of Europe, and many people drive long distances each day when they go on
holiday - sometimes as much as 1,000 km or more. So they might need to
refuel several times, especially if they don’t want to let the fuel level
get low.

      2. Why would the vehicle odometer be close to zero rather than
      something more typical of vehicles on the road?

It’s the trip odometer, usually reset to zero at the start of a long trip,
not the total distance travelled by the car since it was new.

      3. Why are so many different people paying for fuel?

Different adult family members or a group of friends travelling in one
vehicle often do this, to share costs.

   2. Using one definitive document is best to avoid inconsistencies. Is
   the GS Guide consistent with
   https://wiki.documentfoundation.org/images/d/d5/Automobile.odb ?

I think it is. I and others have used it occasionally to recreate images.

Jean

#11

In reply to Re: [libreoffice-documentation] Updating the Base Guide
https://listarchives.tdf.io/i/ug-jE_5q7WwrDy5mkIO2wHLX

Thanks Jean.

   1.
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase.html#toc6
   - needs a project purpose statement to give the questions and answers
   context so users can understand the scenario - Note: In our database,
   payments for food or fuel might be made from one of two credit cards (Dan
   or Kevin) or in cash...
   2. Note
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase.html#toc10
   - rename disabled when right-clicking table name (generally works)
   3.
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase.html#toc10
   - deleting a table is discussed, user should be specifically directed to
   delete CD-Jazz table since it does not form part of the production database
   4. Figure 12 (
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase-img/GS7208-GettingStartedWithBase-img013.png
   ) - wiki database does not have field descriptions or Notes field
   5.
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase.html#toc11
   - After Figure 12 numbering within section starts again from 1
   6. At 1 after Figure 12 step and bullet reference is missing in html
   version
   7. above instructions are split between two places in the document which
   can't be seen at the same time, repeat details here. Suggest "Format
   currency same as 3C..."
   8. (Note: Can select multiple fields and apply same attributes but they
   are not saved)
   9. SnCost field does not exist but Snackcost does
   10. (Note: Can copy table from external database copies Field Name and
   Type but not Description and Field Properties)
   11.
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase.html#toc13
   - The topic is dealt with in detail in the Base Guide and will not be
   pursued further here - Where in Base Guide?
   12.
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase-img/GS7208-GettingStartedWithBase-img026.png
   - Note fields inverted
   13. Chapter reviewed to before
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase.html#toc15

The Automobile database makes a nice demo. I accept the Fuel table
explanation but I challenge the reasonableness and suggest the following:

   1. Although the GS Guide does not reference
   https://wiki.documentfoundation.org/images/d/d5/Automobile.odb the two
   are inconsistent but there seems to be a single source needing an update
   2. An odometer is clearly not a tripmeter and in reality, an odometer
   would be used for this purpose not a tripmeter (which would be impractical
   to zero at the start of every trip, especially unplanned trips) so increase
   the numbers to reflect typical odometer readings
   3. See point 1 at top of this email and note Payment type would be
   clearer explained in Planning a database
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase.html#toc6
   - btw it is really two fields; who and what eg Dan's card, Kevin's cash
   4. Data in
   https://books.libreoffice.org/en/GS72/GS7208-GettingStartedWithBase-img/GS7208-GettingStartedWithBase-img036.png
   showing refueling five times in one day is not credible and can't be
   explained by long journeys so it needs fixing, especially in the wiki
   version

[image: image.png]

#12

Thank you for the excellent suggestions. I don't think anyone has done
a thorough review of that chapter in several years; I know I have not
looked closely at it, or at the automobile.odb. Now we need someone to
actually make the changes, in both the database and the chapter. I'll
do it if no one else does, but not soon.

Jean

#13

I'd already reworked
https://nextcloud.documentfoundation.org/apps/files/?dir=/LibreOffice%20Documentation/English/Getting%20Started%20Guide/7.3/Work%20in%20Progress&fileid=701926
Planning a database first point and renamed the last. Systems analysis and
design in a single page aimed at all users is a challenge. I figured I'd
apologise if I offended anyone and the change could be undone.

There are a lot of differences with Automobile.odb and I thought I'd update
it but I think the Fuel form is too challenging to reproduce exactly. Can
someone make the Automobile.odb used to produce the guide available, maybe
by replacing the Relational database sample under
https://wiki.documentfoundation.org/Documentation/Publications#Base ?

#14

I've hunted around to see if I could find your reviewed copy of that
chapter, but I can't find it. I have no idea what may have happened to
it.

Please do whatever you think is necessary to fix the chapter,
including updating the info on JRE/JDK for macOS.

I apologize for not responding earlier about Automobile.odb. I have
now found a more comprehensive version of that file and put it here:
https://nextcloud.documentfoundation.org/apps/files/?dir=/LibreOffice%20Documentation/English/Contributor%20Resources&fileid=81380
It may be the one used for the illustrations in that chapter. I'm sure
some of the data needs improvement, so please feel free to update it
and replace screenshots as needed in the chapter.

The copy on the wiki is, I think, deliberately lacking in detail so
people following the tutorial can fill it in themselves, so I have not
replaced it.

Jean

#15

GS7308-GettingStartedWithBase_FW_20220205.odt was updated including
comments in the document that can mostly be deleted and held over to
consider in another version. Changes were mainly tweeks to the
Automobile.odb example database and guide to make the guide and the example
database consistent. The database has been updated to be consistent with
the guide: https://nextcloud.documentfoundation.org/f/836433

An issue for future consideration is making the vacation expenses example
more credible. The fuel form is actually a vacation expense form with a
one-to-many relationship between vacation date and fuel date. Many
expense dates are required to get a realistic fuel dataset. To simplify the
example all fuel records have been entered for a single date which lacks
credibility and makes it confusing. As a minimum, moving fiirst and last
fuel record to an expenses record for a date before/after would make it
more realistic and relatable.

Impressum (Legal Info) | Datenschutzerklärung (Privacy Policy)   Content on this site is licensed under a Creative Commons Attribution Share Alike 3.0 license.