Thread: pgAmin III 1.18.0 docs.
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
Barry Gysbers <barrygysbers@gmail.com> 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 > postgresql-9.3.0-1-windows.exe 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. > 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. 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. > 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 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