Base guide structure (TOC)

Hi all,

I know that I am the "new" guy here, but I have been thinking about a Base
guide for awhile now. The current layout looks vague to me and doesn't seem
to address the basic idea of a user guide; to show how to use the software.
Database concepts are not simple and we should focus on how to use Base and
leave tutorials and concepts for the appendices. With too much basic (or
remedial) instruction on design theory and such, we lose the attention of
users who know about databases at various levels. I don't think this is how
a guide should be written. Below you can see how we worked out the Calc
guide. It has minimal explanations of spreadsheet concepts and design.

     I really don't see what the vague look of the Base outline is that
you mention, nor do I understand what you mean by "basic idea of a user
guide."
What database concepts are not simple? What are you referring to when
mentioning tutorials?
     My problem centers around who is the Base Guide for? What is the
expected level of database knowledge of the user? How many of them have
a background in database theory? How many do not? How can we know the
answer to these questions? How do we write the guide to cover both
groups without seemingly too elementary for some and too difficult for
others? (Some have stated that an address book type database is as
complex as the Base Guide should get. Others have mentioned that even
relational databases should be kept as simple as possible using only the
wizards.)
     To me, an outline is vague or clear depending upon how detailed the
outline is. I looked over your proposed outline, and to me it looks
vague. Why? Because I don't see the details of your outline. For that
matter, Drew's outline could use more details that would make it
clearer.
     My perspective of Drew's outline: it compartmentalizes the
discussion into chapters.
     Chapter 1 is an introduction.
     Chapter 2 describes how to plan/design a database. (Considering
some of the posts to the user mailing list and personal experience, I
question how many people actually do this very well at all.) I consider
this to be one of the most important parts for creating a database: not
needed for the expert who takes the time to do the needed
planning/designing every time; an Absolute must for those who have not
always done this or never have done it. (Proper planning/designing
reduces if not eliminates the GIGO [garbage in garbage out] that can
become part of a poorly designed database.)
     Chapter 3 looks at the details of tables, views, relationships, and
forms. If a person wants to know how to create, modify, or delete these,
this is where they should look.
     Chapter 4 discusses Queries and Reports. Again, anyone wanting to
know about any of these should look here.
     Other chapters are similar in nature: look in this chapter for
discussion on what you can do with the parts of Base mentioned here.

Showing how to plan and design the database which is used as an example
throughout the guide is a very good idea.

     I disagree. This is not how a database should be created: plan and
design it as it is being created. It needs to first have a plan.
Secondly, it needs to have a design based upon that plan. Then if a
problem comes up while creating the database, the plan and then design
should be adjusted before continuing with the creation of it.
     I see a pattern in Drew's outline for creating a database. First
you plan and design, Then you create the tables and the relationships
between them. Next you create most of the forms you will need (forms
that contain queries are created after them). Next, you create your
reports. Now comes the uses for the created database. Next, learn how to
customize the database. Finally comes the most complex (accessing Base
database document files with embedded databases using the HSQLDB as well
as using Base as the front-end to databases created by other programs
(Access, MySQL, Oracle, PostgreSQL, etc.).

I have included my ideas (Proposed TOC) at the bottom just below the current
layout.

     So, are you suggesting that we essentially begin from scratch? That
the outline we have presently can not be modified in terms of the
details in the outline to make it better? Perhaps a rearrangement of a
chapter? (Specifically, using Base as a front-end might need to be moved
to chapter 5.)
     A plan for the Base Guide is similar to a plan for a database.
There are very often many ways to do the same thing. The differences
come in the viewpoint of the developers. Which one is better, yours or
Drew's? Likely the differences is also a matter of Drew's and your
viewpoints. But most importantly, the details of either outline must be
considered.

    <BIG SNIP>

Proposed TOC

Chapter 1 - Introducing Base

Obvious, but omit the tutorial on database concepts and stick to the working
environment. This should be in an appendix.

Chapter 2 - Opening existing Datasources

Explain how to connect to the various types of Datasources including setting
up JDBC and ODBC connectors

Chapter 3 - Creating a new Database

Explain how to use a native base database and the features (or lack of them)
of the current version of HSQLDB. Maybe a portion on the Base Document File

Chapter 4 - Tables

Designing, creating, and viewing with Base

Chapter 5 - Relationships

Managing relationships. Maybe a portion on types of relationships, but not a
tutorial

Chapter 6 - Queries

How to query Datasources using Base. Refer to appendix C for "How-to SQL"

Chapter 7 - Forms

Designing, creating and using Forms

Chapter 8 - Reports

Report writing using Base

Chapter 9 - Importing and Exporting Data

Self-explanatory?

Appendix A - Basic Database Concepts

Here you could place some of the text from the current "Introducing Base"
which does not address how to use Base, but rather database design and
theory.

Appendix B - Tutorial - Creating a database

Here you could place the current chapter "Planning/Designing your Database
". This database could be used for examples throughout the guide...or we
could have another?

Appendix C - SQL Statements and Functions

A chart of SQL Statements and Functions which are compatible with Base

Appendix D - (Feature) Comparison of Compatible Databases

Maybe a short listing to show what might be the most acceptable Data source
for a user by way of the feature set?

Rick

--Dan

Hi Dan,

Let me explain my point better than I did last night.

I really don't see what the vague look of the Base outline is that you mention, nor do I understand what you mean by "basic idea of a user guide."

The current toc looks like this. Correct?

1 Introducing Base
2 Planning/Designing your Database
3 Data Input and removal
4 Data Output
5 Exchanging Data
6 Customizing your Database Design
7 More Customization
8 Using Base at Work
Appendix I Build the Example Database
Appendix II Overview of a Database
Appendix III Further Reading on Database Design
Appendix IV Editing the Base Document File

This is quite different from the other guides, Which is why I had the Calc guide toc in my e-mail. As a software user, say I wanted to learn how to use Styles with Writer. I would go to the chapter titled "Working with Styles". Likewise if I wanted see about adding graphics to a Calc spreadsheet I would go to the chapter "Using Graphics in Calc". With the current Base guide layout where do I look for report writing with Base? Or querying a database? A guide should clearly make this available to a user.

And "Using Base at Work", is this about multi-user or networked databases, or what?

What database concepts are not simple? What are you referring to when mentioning tutorials?

Database concepts are not as easy to understand as using a spreadsheet or working with a text document. I know, I taught these subjects in college and database design and implementation is a dense subject, even for me. But regardless, it is not the place of a guide to pander to the lowest denominator. Users of all levels may need to use the guide to learn how to use Base.

As I wrote:

With too much basic (or remedial) instruction on design theory and such, we lose the attention of users who know about databases at various levels.

Chapter 2 describes how to plan/design a database. (Considering some of the posts to the user mailing list and personal experience, I question how many people actually do >>this very well at all.) I consider this to be one of the most important parts for creating a database: not needed for the expert who takes the time to do the needed >>planning/designing every time; an Absolute must for those who have not always done this or never have done it. (Proper planning/designing reduces if not eliminates the GIGO >>[garbage in garbage out] that can become part of a poorly designed database.)

This is what I mean about a tutorial. I believe a software guide shows how to use the software. What you wrote is true as far as database work is concerned. But that is what I meant by tutorial, you are teaching about concepts and database design, not about Base and how to use it.

I looked over your proposed outline, and to me it looks vague. Why? Because I don't see the details of your outline. For that matter, Drew's outline could use more details >>that would make it clearer.

My outline was a "for example", I don't want to step on anyone's toes here. However it does more closely follow the outlines of the other guides. Like I said a few line above the outline (Or TOC) should make it easy for a user to "jump" to the information they need.

The "Introducing Base" does a good job of introducing Base and adds information that belongs elsewhere. Look at the Calc or Writer "Introducing..." chapters.

Another problem I see is that the current outline makes it hard for someone, like me, to take on a chapter of my own (as we did with previous guides). If the outline (TOC) was like the other guides I could write a chapter on Report writing or Querying the database or creating a using tables? Compartmentalized is what I have suggested.

I see a pattern in Drew's outline for creating a database

True, but we are supposed to be writing a software guide.

How do you know if the greater number of Base users are using it for a frontend or a native DB? And, as far as a software guide is concerned why would you care...just explain how to do it.

So, are you suggesting that we essentially begin from scratch?

No, but I am pointing out the differences the Base guide from the other already published guides.

The differences come in the viewpoint of the developers.

Although I am a very good developer, I am here to be a technical writer.

A plan for the Base Guide is similar to a plan for a database.

I disagree. But we should continue this discussion as I would like to get busy and write.

Regards,

Rick B

May I disagree?
It is user's guide, not a computer science text. What does need to know
the user is how it works and how to use it. What things can do with
this specific program and what things can not. The stuff about design
and similar is not of immediate interest for the user. May be we can
dedicate a chapter called something like "Design and details of
databases", and in there you can put all this technical things. But is
not a good idea, mixing design and using items in the same chapter. Is
just a confusion focus.
And tutorials is not for all using instructions. Is just for specific
points like "How can I change background colour?", "How can I insert a
picture?".
For general using things, there's documentation (including user's
guides), wiki pages and FAQ's.
Is my opinion.

Regards
Sylvia