Обсуждение: Re: [DOCS] 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