Re: Change to documentation headers - Mailing list pgsql-docs

Peter, based on feedback we have received, I think our users want our
docs header to look the same as our docs footer, i.e. few people see
the value of Fast Forward and Fast Backward, and they want "Up" to be in
the header.  You seem to have done all the substantive changes to
stylesheet.dsl --- would you make these changes?  Thanks.

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

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... :)

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

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