From: Chris Meller <chris@doesnthaveone.com>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Subject: Documentation Navigation Feedback
Date: Thu, 13 Jan 2011 21:49:24 -0500
Message-Id: <8C378959-1A31-45DB-846D-4EEFAD747CB4@doesnthaveone.com>
To: pgsql-docs@postgresql.org
Mime-Version: 1.0 (Apple Message framework v1082)

I jumped into #postgresql earlier to ask a couple of questions and we =
ended up talking about the documentation. agliodbs wanted me to mention =
the problems I ran into trying to find what I was looking for on the =
mailing list, so here we go.

I was looking at the documentation (which, btw, has always been of a =
very high quality, so props for that!) and trying to find out about =
character sets and collations. I didn't have much luck looking at the =
main TOC, which isn't a big deal or terribly unexpected, so I did a =
search for 'collation'. The second result is the CREATE DATABASE =
reference page, which is one of the main pages I was looking for, so =
that's great.

Once I'm there, though, I'm pretty much lost. I've got Prev and Next =
links (and Fast Backward and Fast Forward, which didn't seem to do =
anything different), but no indication of where I am or how to get =
somewhere else.

For a specific example: After reading the few pieces I needed to know =
about for CREATE DATABASE, I wanted to move on to CREATE TABLE. It looks =
like I'm in a function reference section, so I assume there must be a =
main TOC page listing them all, but I don't see a link to that anywhere. =
There's also no indication which chapter and section I'm in, so I can't =
go back to the main TOC and navigate down to it to find the chapter TOC. =
I ended up hitting 'Next' a dozen times to find CREATE TABLE in the =
alphabetical list of functions.

When I mentioned this out on IRC, peerce did point out that there's an =
'Up' link... at the bottom. I had no idea it was there. I'd found the =
parameter I was looking for and had no reason to keep reading the rest =
of the lengthy explanation of other parameters and caveats to using =
them, so there was no reason for me to keep scrolling and I didn't =
expect the navigation link I was looking for to be at the bottom.

Once I was looking at the navigation at the bottom, it seemed like it =
should be the navigation at the top of the page instead. There's an 'up' =
link and the Prev and Next links include the title of the pages you'd be =
moving to, which is actually nice to know.

On other pages I saw that the chapter was shown under 'PostgreSQL x.y =
Documentation' in the navigation at the top, so I don't know why there =
wasn't a similar title on the function page.

Expanding the breadcrumbs at the top, which only show that you're in the =
PostgreSQL x.y documentation, to include the location in the =
documentation would pretty much eliminate my problem... So would using =
the save left-column navigation bar all the other pages seem to use.

Anyway, there's my feedback. Great documentation, but confusing =
navigation makes it tough to use. Carry on... :)

Thanks!

Chris=