From: Bruce Momjian <bruce@momjian.us>
Message-Id: <201101142053.p0EKr6R18322@momjian.us>
Subject: Re: [DOCS] Documentation Navigation Feedback
In-Reply-To: <8C378959-1A31-45DB-846D-4EEFAD747CB4@doesnthaveone.com>
To: Chris Meller <chris@doesnthaveone.com>
Date: Fri, 14 Jan 2011 15:53:06 -0500 (EST)
CC: PostgreSQL www <pgsql-www@postgresql.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset="US-ASCII"


I am forwarding this email to the www team in case there is something
that can be done to improve our website's display of documentation:

---------------------------------------------------------------------------

Chris Meller wrote:
> 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 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +