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 El lun, 19-03-2012 a las 19:18 -0700, Mail Dump escribió: > 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 > --------------------------------------------------------------------- > Still in all, every night we does the tell, so that we 'member who we was and > where we came from... And we lights the city, not just for him, but for all > of them that are still out there. 'Cause we knows there come a night, when > they sees the distant light, and they'll be comin' home. > > -- Mad Max Beyond Thunderdome > > > > -----Original Message----- > From: Dan Lewis [mailto:elderdanle...@gmail.com] > Sent: Monday, March 19, 2012 7:43 AM > To: documentation@global.libreoffice.org > Subject: Re: [libreoffice-documentation] Base guide structure (TOC) > > On Sun, 2012-03-18 at 23:46 -0700, Mail Dump wrote: > > 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 > > > > > -- > Unsubscribe instructions: E-mail to documentation+h...@global.libreoffice.org > Problems? > http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ > Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette > List archive: http://listarchives.libreoffice.org/global/documentation/ > All messages sent to this list will be publicly archived and cannot be deleted > > -- Unsubscribe instructions: E-mail to documentation+h...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette List archive: http://listarchives.libreoffice.org/global/documentation/ All messages sent to this list will be publicly archived and cannot be deleted
