SQL HOWTO

[Jon Lapham]

Linas Vepstas wrote:
> On Tue, Sep 23, 2003 at 12:49:47PM -0300, Jon Lapham was heard to remark:
> 
>> Linas et al-
>> 
>> I noticed you put a link to the SQL HOWTO document on the web site under 
>> the documentation section sidebar.
>> 
>> I've been trying to minimize the number of links to documents from the 
>> web site.  
> 
> 
> I noticed. I am not sure that is a good idea.  One of my big complaints
> about other projects is inadequate, hard-to-find documentation.  
> Primary refernces should be one click away from the main page, not two
> or more.

Where were you for the WEEKS of discussion that went on about this!

>> I know we have a lot of things (like the SQL HOWTO, the main 
>> README, the translators howto, the business howto, etc, etc) that we 
>> need to make available to people.  However, I think we need to organize 
>> the presentation of this material so as to not make GnuCash look like it 
> 
> OK, but no one has done that yet.

No one has done that!  I hope you are joking.  I have spend a great deal 
of time incorporating a wide range of scattered docs into the official 
GnuCash docs.  Would you like a list?  You can begin by reading the 
business section... and comparing it to the various other scattered 
piece of info we have floating around.

 > p.s. I moved and modified docs.phtml so it adheres to the style of the
 > rest of the site.

Which entails what?  Rather than just changing stuff and making comments 
like "...I modified...", why not *teach* us that want to help to not 
make the same mistakes again.  Geesh, this is "working with others 101".

>> is a geeks-only application.  And, I'll tell you, when my grandmother 
>> reads a link called "SQL HOWTO" on the main page, her eyes will glaze 
>> over...
> 
> I resent the deprecation involved. This has nothing to do with geeks, 
> or your grandmother.  Your grandmother won't read it.  Its not for 
> your grandmother.

There was no deprecation involved.  In what way does my saying that a 
newbie's eyes glazing over is belittling the work?  Tons of stuff I 
write for GnuCash would have the same effect.

I think you are wrong.  But, fine, your opinion.

> One problem with a lot of commercial products is thier stupidification
> of the user.  In the name of "making it easy/simple" they make it harder
> for the average user.  Don't treat your users as idiots.

We agree 100% on this point.  My philosophy is to make everything 
available, don't hide anything.  But, that doesn't mean that we need to 
make things look so complicated that it is intimidating to new users.

> Why?  It makes the important links harder to find, farther away from
> the user.   I've already scratching my head as to why we moved the links
> there.  It makes the site harder to navigate, and it makes it harder
> to find things.  If we want to make the site easy to use, the links 
> should be on the main menu, not buried, as if we were embarrassed to
> show them to anyone.

You didn't say anything earlier!  My goodness, where were you during the 
messages I sent to the list BEFORE doing anything?!

I will be happy to add the links back to the main page.  I thought I was 
making things better.  Sorry.  Believe me, I won't make that mistake again.

So, just to make sure I understand what you want, the "Documentation" 
section in the sidebar should have the following links:

Help v1.8 (en)
Help v1.8 (de)
Concepts Guide
Wiki (en)
Wiki (de)
Business User Guide
Joe Mack's Tutorial
Dave Gilbert's User Guide
Docs v1.6 (en)
Docs v1.6 (de)
Docs v1.6 (es)
Docs v1.6 (pt)
Docs v1.4 (fr)
Bugzilla Doc Bugs
DocBook Definitive Guide
DocBook XSL
Gnome HIG
Gnome Doc Style
Gnome Handbook of Writing Software

Linas-

You have really pissed me off.  Goodbye.

Sincerely,
Jon

-- 

-**-*-*---*-*---*-*---*-----*-*-----*---*-*---*-----*-----*-*-----*---
  Jon Lapham  <lapham at extracta.com.br>          Rio de Janeiro, Brasil
  Work: Extracta Moléculas Naturais SA     http://www.extracta.com.br/
  Web: http://www.jandr.org/
***-*--*----*-------*------------*--------------------*---------------