Documentation Navigation Feedback

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. +

On 15 January 2011 07:53, Bruce Momjian <bruce@momjian.us> wrote:

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:

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

On Fri, Jan 14, 2011 at 21:53, Bruce Momjian <bruce@momjian.us> wrote:

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:

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/

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.

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

On Fri, Jan 14, 2011 at 4:21 PM, Brendan Jurd <direvus@gmail.com> wrote:

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.

+1 for the latter.

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?

IMHO, no.

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

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. +

On ons, 2011-02-02 at 20:13 -0500, Bruce Momjian wrote:

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.

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.

Peter Eisentraut wrote:

On ons, 2011-02-02 at 20:13 -0500, Bruce Momjian wrote:

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.

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.

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".

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

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

On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote:

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".

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

Chris Meller wrote:

On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote:

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".

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.

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

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

Bruce Momjian wrote:

Chris Meller wrote:

On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote:

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".

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.

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?

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

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

Bruce Momjian wrote:

Bruce Momjian wrote:

Chris Meller wrote:

On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote:

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".

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.

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?

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.

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

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

Bruce Momjian wrote:

Bruce Momjian wrote:

Bruce Momjian wrote:

Chris Meller wrote:

On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote:

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".

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.

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?

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.

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?

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

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

Peter, any status on this?

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

Bruce Momjian wrote:

Bruce Momjian wrote:

Bruce Momjian wrote:

Bruce Momjian wrote:

Chris Meller wrote:

On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote:

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".

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.

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?

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.

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?

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

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

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

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

On fre, 2011-03-11 at 07:07 -0500, Bruce Momjian wrote:

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.

Peter Eisentraut wrote:

On fre, 2011-03-11 at 07:07 -0500, Bruce Momjian wrote:

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.

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

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

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

Bruce Momjian wrote:

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.

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?

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

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

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

Bruce Momjian wrote:

Bruce Momjian wrote:

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.

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?

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

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

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

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