Subject: Documentation Navigation Feedback

From: Chris Meller <[email-masked]>
Date: Thu, 13 Jan 2011 21:49:24 -0500

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

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 14 Jan 2011 15:53:06 -0500 (EST)

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 ([email-masked])
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-docs

--
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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

---

From: Brendan Jurd <[email-masked]>
Date: Sat, 15 Jan 2011 08:21:29 +1100

> that can be done to improve our website's display of documentation:

I thoroughly agree with Chris' comments.  The docs have excellent
content but are somewhat unwieldly.

The navigation links at the bottom are much more useful than the ones
at the top, we might want to swap these around, or perhaps just
duplicate what's currently at the bottom to both locations.

I have never used "Fast {Back,For}ward", and after playing around with
them a bit, I still don't see the point.  Does a feature this obscure
really deserve the prime real estate it currently occupies?

I think I understand why the breadcrumbs stop at "PostgreSQL 9.0" --
the HTML docs themselves are generated from the doc sources in the
core project, but the breadcrumbs are part of the webpage container,
so they have no knowledge of the docs' internal structure.  Still, if
we could find some way to extend the breadcrumbs all the way down to
the current page, it would be a big step up in usability.

Cheers,
BJ

---

From: Magnus Hagander <[email-masked]>
Date: Sat, 15 Jan 2011 10:49:17 +0100

> that can be done to improve our website's display of documentation:

No, it properly belongs on the -docs list. The website just uses the
HTML output that comes out of the main docs build, so that's where
TOCs and links are made. All the website does is extract the <body>
part an put it inside the framework that adds the logo and the
breadcrumbs - but it doesn't have access to any more metadata than the
filename and the title of the page, so it can't do anything more
advanced. Any improvements there have to be made in the sgml->html
translation step in the main code - or at least that step has to put
the required metadata in the output.

-- 
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

---

From: Josh Berkus <[email-masked]>
Date: Sun, 16 Jan 2011 12:14:55 -0800

> the required metadata in the output.

I remember that somebody did create and submit a left-side floating
navigation window, though.  Andrew as talking about putting it up
somewhere public.  Time to revisit that mod?

-- 
                                  -- Josh Berkus
                                     PostgreSQL Experts Inc.
                                     http://www.pgexperts.com

---

From: Robert Haas <[email-masked]>
Date: Sun, 16 Jan 2011 20:54:48 -0500

> duplicate what's currently at the bottom to both locations.

+1 for the latter.

> really deserve the prime real estate it currently occupies?

IMHO, no.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 2 Feb 2011 20:13:38 -0500 (EST)

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.

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 04 Feb 2011 18:01:39 +0200

> stylesheet.dsl --- would you make these changes?  Thanks.

I'll look into it.

Taking the same layout for the header navigation as for the footer
navigation is not a problem.  But the top also shows the current chapter
title.  Note sure if we want to lose that or show it somewhere
different.

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 4 Feb 2011 16:23:34 -0500 (EST)

> title.  Note sure if we want to lose that or show it somewhere

Thanks.  I studied stylesheet.dsl but was unable to understand how to
modify it.

Looking at the 9.0 docs now:

	http://www.postgresql.org/docs/9.0/static/tutorial-fk.html

I do like the chapter title there.  

Looking at "Home", we actually have two of them.  The "Home" at the top
left of the page links to the PG homepage, while the "Home" at the
bottom goes to the top of the 9.0 documentation.  That seems odd.  Maybe
we need to remove the "Home" at the bottom, or rename it.

You could get away with changing "Fast Backward" to "Up" and removing
"Fast Forward".

---

From: Chris Meller <[email-masked]>
Date: Fri, 4 Feb 2011 17:48:54 -0500

> You could get away with changing "Fast Backward" to "Up" and removing

I like the title and chapter reference at the top. The "PostgreSQL x.y.z Documentation" title serves the same purpose as 'Home' at the bottom, so it should be fine as-is. Making the chapter a link to the same destination as 'Up' would make sense to me... You want to go up to the chapter TOC and that's what I would expect to get if I clicked on a chapter link (just as if I clicked on it in the main TOC).

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 4 Feb 2011 20:03:05 -0500 (EST)

Chris Meller wrote:
> I like the title and chapter reference at the top. The "PostgreSQL
> x.y.z Documentation" title serves the same purpose as 'Home' at the
> bottom, so it should be fine as-is. Making the chapter a link to the
> same destination as 'Up' would make sense to me... You want to go up
> to the chapter TOC and that's what I would expect to get if I clicked
> on a chapter link (just as if I clicked on it in the main TOC).

That is an interesting idea.  I thought we had sub-sub-pages, but we
don't --- every subpage has a chapter that should be the same as UP.  I
think making that title a link is a great idea.  I think we can still
remove fast forward/backward as just being too confusing.

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 4 Feb 2011 20:07:06 -0500 (EST)

> remove fast forward/backward as just being too confusing.

Oops, a problem.  On this chapter page:

	http://www.postgresql.org/docs/9.0/static/errcodes-appendix.html

there is no chapter name, and hence no "up" link for us, and we need one
there.  Perhaps we need a link to "VIII. Appendixes" there.  Peter, can
that be done?

---

From: Bruce Momjian <[email-masked]>
Date: Sat, 5 Feb 2011 10:55:05 -0500 (EST)

> there.  Perhaps we need a link to "VIII. Appendixes" there.  Peter, can

More thinking --- "PostgreSQL 9.0.3 Documentation" at the top center is
already clickable, so that can act as the home.  Let's duplicate that at
the bottom too.

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 7 Feb 2011 21:00:16 -0500 (EST)

> already clickable, so that can act as the home.  Let's duplicate that at

OK, so here is a summary:

	o  remove fast forward/backward links
	o  add book title where there is no heading
	o  make book and chapter titles as links
	o  make the bottom footer match the top header

Can we backpatch this to 8.2 so all our online documentation has it?

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 11 Mar 2011 07:07:25 -0500 (EST)

Peter, any status on this?

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 15 Mar 2011 22:28:28 +0200

> Peter, any status on this?

The summary below doesn't make much sense to me.  I'll play around with
it a little more, but while I understand the goals, the concrete
solution isn't yet clear.

---

From: Bruce Momjian <[email-masked]>
Date: Sat, 7 May 2011 22:33:20 -0400 (EDT)

> solution isn't yet clear.

Peter, where are we on this?  We discussed it at PG East.

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 10 Oct 2011 22:08:35 -0400 (EDT)

> Can we backpatch this to 8.2 so all our online documentation has it?

I have developed the attached patch which implements an "Up/Home" link
at the top of the page in place of the "Fast Backward" link, and removes
the "Fast Forward" link.  It says "Up", unless you are already at the
book title, in which case it says "Home".

While this isn't ideal, it is probably good enough to make things easier
for users.  This might be nice to backpatch so all our docs have the
same navigation links.

You can view the built docs here:

	http://momjian.us/expire/pgsql/index.html

  + It's impossible for everything to be true. +
diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl
new file mode 100644
index 637758f..2c18dab
*** a/doc/src/sgml/stylesheet.dsl
--- b/doc/src/sgml/stylesheet.dsl
***************
*** 284,290 ****
  
  ;; Customization of header, add title attributes (overrides
  ;; dbcommon.dsl)
! (define (default-header-nav-tbl-ff elemnode prev next prevsib nextsib)
    (let* ((r1? (nav-banner? elemnode))
  	 (r1-sosofo (make element gi: "TR"
  			  (make element gi: "TH"
--- 284,290 ----
  
  ;; Customization of header, add title attributes (overrides
  ;; dbcommon.dsl)
! (define (default-header-nav-tbl-ff elemnode prev next)
    (let* ((r1? (nav-banner? elemnode))
  	 (r1-sosofo (make element gi: "TR"
  			  (make element gi: "TH"
***************
*** 298,305 ****
  				      (nav-banner elemnode)))))
  	 (r2? (or (not (node-list-empty? prev))
  		  (not (node-list-empty? next))
- 		  (not (node-list-empty? prevsib))
- 		  (not (node-list-empty? nextsib))
  		  (nav-context? elemnode)))
  	 (r2-sosofo (make element gi: "TR"
  			  (make element gi: "TD"
--- 298,303 ----
***************
*** 323,337 ****
  					     (list "WIDTH" "10%")
  					     (list "ALIGN" "left")
  					     (list "VALIGN" "top"))
! 				(if (node-list-empty? prevsib)
! 				    (make entity-ref name: "nbsp")
! 				    (make element gi: "A"
! 					  attributes: (list
! 						       (list "TITLE" (element-title-string prevsib))
! 						       (list "HREF"
! 							     (href-to
! 							      prevsib)))
! 					  (gentext-nav-prev-sibling prevsib))))
  			  (make element gi: "TD"
  				attributes: (list
  					     (list "WIDTH" "60%")
--- 321,329 ----
  					     (list "WIDTH" "10%")
  					     (list "ALIGN" "left")
  					     (list "VALIGN" "top"))
! 				(if (nav-up? elemnode)
! 				    (nav-up elemnode)
! 				    (nav-home-link elemnode)))
  			  (make element gi: "TD"
  				attributes: (list
  					     (list "WIDTH" "60%")
***************
*** 340,360 ****
  				(nav-context elemnode))
  			  (make element gi: "TD"
  				attributes: (list
! 					     (list "WIDTH" "10%")
! 					     (list "ALIGN" "right")
! 					     (list "VALIGN" "top"))
! 				(if (node-list-empty? nextsib)
! 				    (make entity-ref name: "nbsp")
! 				    (make element gi: "A"
! 					  attributes: (list
! 						       (list "TITLE" (element-title-string nextsib))
! 						       (list "HREF"
! 							     (href-to
! 							      nextsib)))
! 					  (gentext-nav-next-sibling nextsib))))
! 			  (make element gi: "TD"
! 				attributes: (list
! 					     (list "WIDTH" "10%")
  					     (list "ALIGN" "right")
  					     (list "VALIGN" "top"))
  				(if (node-list-empty? next)
--- 332,338 ----
  				(nav-context elemnode))
  			  (make element gi: "TD"
  				attributes: (list
! 					     (list "WIDTH" "20%")
  					     (list "ALIGN" "right")
  					     (list "VALIGN" "top"))
  				(if (node-list-empty? next)

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 12 Oct 2011 11:24:52 -0400 (EDT)

> 	http://momjian.us/expire/pgsql/index.html

Applied to head, 9.0.X, and 9.1.X.