Subject: pgAmin III 1.18.0 docs.

From: Barry Gysbers <[email-masked]>
Date: Mon, 6 Jan 2014 08:18:42 -0800

2014Jan07 07:56

Greetings!

I am an experienced database user/programmer.  I am absolutely brand new to
PostgreSQL.  I just downloaded 9.3.0 on 2013Oct01 and am finally getting
over my reluctance to learn a new system and taking a look at it.  The file
was

postgresql-9.3.0-1-windows.exe

and this email refers to the documentation that came with that package.

I started reading the documentation today for pgAdmin III 1.18.0 as it
seems that I must use pgAdmin III in order to get any work done.  I have
only read about a dozen pages before becoming overloaded.  With the
exception of changing the passworld, I have no idea what I read means, nor
the significance of any of it.  I would think that it would be more helpful
to either explain what you are expected to already know before being able
to use the documentation, or, (more skillfully), put links that explain
what each technical term means, and/or what relevance/consequence each
decision you make has.

Otherwise, I have no idea when or where I will ever run into that
particular jargon ever again, and the wondrous possibility that context
will suddenly make things clear that were obscure the first time around.

Mostly, I just wanted to point out that there are an absolutely incredible
number of typos on the very few pages that I have slogged through so far.
It is clear that nobody has read this documentation in ages, as it would be
impossible for any alert human being to miss them.  I imagine that most of
them are a result of prior editing, and that the final result might
actually be better than the previous version of the documentation, but
there can be no excuse for failing to run any prepared text through a spell
checker, which would catch a large number of the typos.

I would be happy to provide at least some editing services as my
contribution to the project, (being absolutely ignorant of anything
actually useful), provided there was some guarantee that they would
actually be implemented or otherwise used.

I would have to be told exactly how to go about making changes in a way
that would be considered useful.  I am guessing that merely submitting a
list of the text with typos and providing my suggested corrections would
likely not be input, as this work is very boring for most people.

Thanks for your consideration,

Barry Gysbers

---

From: Kevin Grittner <[email-masked]>
Date: Tue, 7 Jan 2014 07:32:40 -0800 (PST)

Barry Gysbers <[email-masked]> wrote:

> I am an experienced database user/programmer.  I am absolutely
> brand new to PostgreSQL.  I just downloaded 9.3.0 on 2013Oct01
> and am finally getting over my reluctance to learn a new system
> and taking a look at it.  The file was

Welcome to the PostgreSQL world!  One of the first things you might
want to check out is the page regarding versioning:

http://www.postgresql.org/support/versioning/

In PostgreSQL we are very conservative about what goes into a minor
release (where the numbers don't change to the left of the second
dot); only fixes for security vulnerabilities and serious bugs are
considered for a minor release, and conversion of the database is
never required.  This is so that users can upgrade with minimal
risk that anything will be broken by applying the bug fixes.  With
9.3.0 you are missing three months worth of bug fixes.  I recommend
that you grab the latest 9.3 minor release, to avoid finding all
the "dot zero" bugs which others have already found and fixed.  It
generally pays to stay fairly up-to-date as new minor releases
become available.

> I started reading the documentation today for pgAdmin III 1.18.0
> as it seems that I must use pgAdmin III in order to get any work
> done.

While some packagers may include pgAdmin with the PostgreSQL
distribution, it really is a separate product.  The interface which
is included with PostgreSQL is psql, a command-line tool which is
very flexible and helpful.  It is probably worth trying that out,
just so you are familiar with some of what it can do.

> I have only read about a dozen pages before becoming
> overloaded.  With the exception of changing the passworld, I have
> no idea what I read means, nor the significance of any of it.  I
> would think that it would be more helpful to either explain what
> you are expected to already know before being able to use the
> documentation, or, (more skillfully), put links that explain what
> each technical term means, and/or what relevance/consequence each
> decision you make has.

You may want to start with the documentation for the database
product itself before dealing with the docs for a GUI tool to work
with the database; that might give the background which would allow
the tool's docs to make more sense.

http://www.postgresql.org/docs/9.3/static/index.html

Of course, that doesn't mean that the pgAdmin docs couldn't be
improved; I'm just suggesting it as a way to get the information
you want from existing docs.

> Mostly, I just wanted to point out that there are an absolutely
> incredible number of typos on the very few pages that I have
> slogged through so far.

> contribution to the project, (being absolutely ignorant of
> anything actually useful), provided there was some guarantee that
> they would actually be implemented or otherwise used.

I don't know about an absolute guarantee, but I would be surprised
if the committers for pgAdmin would ignore corrections.

> I would have to be told exactly how to go about making changes in
> a way that would be considered useful.

Your best bet would be to download the source code from here:

http://www.pgadmin.org/development/git.php

... and submit context diff patches to the pgadmin-hackers list.
The pgsql-* lists are not really the right place for discussion or
submissions for pgAdmin.

--
Kevin Grittner
EDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

-- 
Sent via pgsql-docs mailing list ([email-masked])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs