I jumped into #postgresql earlier to ask a couple of questions and we ended up talking about the documentation.
agliodbswanted me to mention the problems I ran into trying to find what I was looking for on the mailing list, so here
wego.
I was looking at the documentation (which, btw, has always been of a very high quality, so props for that!) and trying
tofind out about character sets and collations. I didn't have much luck looking at the main TOC, which isn't a big deal
orterribly unexpected, so I did a search for 'collation'. The second result is the CREATE DATABASE reference page,
whichis 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'tseem 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
CREATETABLE. 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
backto the main TOC and navigate down to it to find the chapter TOC. I ended up hitting 'Next' a dozen times to find
CREATETABLE 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
ofother parameters and caveats to using them, so there was no reason for me to keep scrolling and I didn't expect the
navigationlink 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
actuallynice 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'tknow 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
locationin the documentation would pretty much eliminate my problem... So would using the save left-column navigation
barall 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