I have briefly skimmed the draft Base Guide chapters on several occasions and have been concerned about several of the same points that Cecilia makes (and, I believe, one or two others have made). I agree that the chapter needs some reorganisation, new and/or rewriten material, and a diagram or two. I think it needs to include some material for inexperienced database users, although some pointers to other documents (including the Getting Started guide chapter and Marino's mid-level tutorial) might suffice. It's always difficult to decide how much explanation about basic concepts to include, no matter which module of OOo we're writing about.
I keep hoping to produce a draft, or at least an outline, of a revised chapter, but so far I've failed to find time to do so. Meanwhile, I also keep hoping that someone like Cecilia will come along and make some further revisions before I get to it. Jean -- Jean Hollis Weber Co-Lead, OpenOffice.org Documentation Project On Sat, 2010-09-11 at 23:15 +0100, Cecilia Cheung wrote: > Hello Zoltan, > Having just quickly scanned through some of the text you suggested, it seems > that there are inconsistency in referring the database engine, some text > referred it as HSQL, while other referred it as HSQLDB. In the world of > databases, MySQL, Microsoft Access, Oracle etc are database management > systems (DBMS), very rarely refer to as database programs.If we are writing a > user guide for Base, the guide should have self contained information clearly > telling the users what they need to know about Base and how to do X,Y,Z. If > we assume our target audience has knowledge of database, then why are we > trying to explain what a database is in the introduction of chapter 1. > Wouldn't it be more beneficial to have a diagram or two showing where Base > sits among the different components of the OOo software suite, what Base is > made up of, the environment it runs on, and which component of the OOo suite > interacts with Base?I find the explanation on table, view, database, data > source very confusing and as a result, additional notes were added in an > attempt to clarify the differences. It is always helpful to have a glossary > of terms for reference. > Cecilia > > > Date: Sat, 11 Sep 2010 21:20:38 +0200 > > From: [email protected] > > To: [email protected] > > Subject: Re: [authors] review helper > > > > Hello Cecilia, > > > > 2010.09.11. 19:27 keltezéssel, Cecilia Cheung írta: > > > Hello Zoltan, > > > Thank you for your info. I have just started reading chapter 1 - > > > Introducing Base.As I am new to this document, I found the following: > > > 1) unclear terminology used - for example: database program2) unclear > > > statement - for example: > > > With > > > the right program called a driver, Base can access databases like > > > these as well as others.3) terms used that have not been introduced or > > > explained, an example is:Base > > > uses the HSQLDB 1.8 > > > database engine to create and later update ODF 1.2 database frontend > > > documents. > > I suppose. may be I wrong, that the readers pick this user guide, after > > they went through "Getting Started with OpenOffice.org 3" > > http://wiki.services.openoffice.org/wiki/Documentation/OOo3_User_Guides/Getting_Started > > > > and they knows database basic terms from GS Base chapter: > > http://wiki.services.openoffice.org/wiki/Documentation/OOo3_User_Guides/Getting_Started/Getting_Started_with_Base > > > Listed above are just a few but not limited areas that I picked up as I > > > was reading.If we assume our target audience has no knowledge of > > > database, then we have to communicate in clear, plain and well structured > > > text. In this occasion, the document seemed to have fallen short of that > > > goal. > > The chapter what you reviewed is a first chapter to the user guide, > > which contain more chapters, when we finished will be a book. > > May be needs to add an annex after last chapter, explanation of all > > database specific terms. > > Zoltan > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
