Thread: Remove stickiness from navigation bar in docs

Hello,

Commit 6679835174a93d5688c649c4feb2604cd6afd2a0 added the site-wide
navigation bar to the docs pages. This navigation bar is stuck to the
top of the browser viewport.

This patch removes the position: fixed style from the navigation bar and
removes the .pg-shout-box padding that compensated for the height of the
navigation bar.

Additionally, since the navigation bar is now no longer permanently on
screen, the main.js script (which only contains code for animating the
navigation bar) is also removed from the docs pages.

Hi,

On 10/18/18 3:16 PM, Matthijs van der Vleuten wrote:
> Hello,
>
> Commit 6679835174a93d5688c649c4feb2604cd6afd2a0 added the site-wide
> navigation bar to the docs pages. This navigation bar is stuck to the
> top of the browser viewport.
>
> This patch removes the position: fixed style from the navigation bar and
> removes the .pg-shout-box padding that compensated for the height of the
> navigation bar.
>
> Additionally, since the navigation bar is now no longer permanently on
> screen, the main.js script (which only contains code for animating the
> navigation bar) is also removed from the docs pages.
>

Thanks for working on this. However, I would suggest we just add in the
shout box to the docs. The reason it had not been applied to docs /
pgarchives was due to a technical limitation on how our caching system
worked. However, Magnus fixed that awhile back and we have been running
it in production successfully for several months on pgweb. It should be
safe to add it to the other areas.

Thanks,

Jonathan

Hi,

On 2018-10-18 16:29:48 -0400, Jonathan S. Katz wrote:
> On 10/18/18 3:16 PM, Matthijs van der Vleuten wrote:
> > Commit 6679835174a93d5688c649c4feb2604cd6afd2a0 added the site-wide
> > navigation bar to the docs pages. This navigation bar is stuck to the
> > top of the browser viewport.

+1 for removing that, I want to read the docs, not loose a portion of my
screen to the navbar. That doesn't matter as much in other parts of the
website, where I'm not going to constantly look at lots of content.


> > This patch removes the position: fixed style from the navigation bar and
> > removes the .pg-shout-box padding that compensated for the height of the
> > navigation bar.
> > 
> > Additionally, since the navigation bar is now no longer permanently on
> > screen, the main.js script (which only contains code for animating the
> > navigation bar) is also removed from the docs pages.
> > 
> 
> Thanks for working on this. However, I would suggest we just add in the
> shout box to the docs.

Add it? It's present right now, no?

I don't like the shout box in the docs, FWIW. For me that's reference
material, and I don't want to waste the space. Currently content starts
like half a screen down when at the top. That's a *lot*.

Greetings,

Andres Freund

On 10/19/18 3:50 PM, Andres Freund wrote:
> Hi,
>
> On 2018-10-18 16:29:48 -0400, Jonathan S. Katz wrote:
>> On 10/18/18 3:16 PM, Matthijs van der Vleuten wrote:
>>> Commit 6679835174a93d5688c649c4feb2604cd6afd2a0 added the site-wide
>>> navigation bar to the docs pages. This navigation bar is stuck to the
>>> top of the browser viewport.
>
> +1 for removing that, I want to read the docs, not loose a portion of my
> screen to the navbar. That doesn't matter as much in other parts of the
> website, where I'm not going to constantly look at lots of content.
>
>
>>> This patch removes the position: fixed style from the navigation bar and
>>> removes the .pg-shout-box padding that compensated for the height of the
>>> navigation bar.
>>>
>>> Additionally, since the navigation bar is now no longer permanently on
>>> screen, the main.js script (which only contains code for animating the
>>> navigation bar) is also removed from the docs pages.
>>>
>>
>> Thanks for working on this. However, I would suggest we just add in the
>> shout box to the docs.
>
> Add it? It's present right now, no?

Ah it is, I've been going through so many pages these past few days I
forgot :)

>
> I don't like the shout box in the docs, FWIW. For me that's reference
> material, and I don't want to waste the space. Currently content starts
> like half a screen down when at the top. That's a *lot*.
>

Well, the things up top are the core doc navigation (versions, search,
TOCs on the page). Those are fairly important, particularly on large
pages. And also on large pages, it can be a pain to scroll all the way
back up if you need to get to another part of the site, or search.

I would say that doubly-so on mobile. Viewing the docs on mobile view, I
would strongly suggest keeping the floating navigation.

I do see it from your viewpoint and I could argue it that way as well,
but I'm not convinced yet, and am definitely not convinced on mobile.

Thanks,

Jonathan

Hi,

On 2018-10-19 17:37:07 -0400, Jonathan S. Katz wrote:
> > I don't like the shout box in the docs, FWIW. For me that's reference
> > material, and I don't want to waste the space. Currently content starts
> > like half a screen down when at the top. That's a *lot*.

You're quoting me saying things about the shout box - but I think you're
talking about the fixed navbar?


> Well, the things up top are the core doc navigation (versions, search,
> TOCs on the page). Those are fairly important, particularly on large
> pages. And also on large pages, it can be a pain to scroll all the way
> back up if you need to get to another part of the site, or search.

It's like one swipe to scroll back up even on big pages, I don't quite
buy that. But I find the mobile header much less intrusive / distracting
than the non-mobile one (Doesn't change size. Only a small symbol, not
multiple links), so I don't care as much.


FWIW, the mobile docs view looks kinda bad when you start out. I've
attached a screenshot from my phone.  The amount of space taken by the
header, by the shoutbox, by the version selectors (man, that's like 5
lines), the search box, the docs header, is more than a bit
disproportional.

Greetings,

Andres Freund

> On 19 Oct 2018, at 23:37, Jonathan S. Katz <jkatz@postgresql.org> wrote:
> 
> Well, the things up top are the core doc navigation (versions, search,
> TOCs on the page). Those are fairly important, particularly on large
> pages. And also on large pages, it can be a pain to scroll all the way
> back up if you need to get to another part of the site, or search.
> 
> I would say that doubly-so on mobile. Viewing the docs on mobile view, I
> would strongly suggest keeping the floating navigation.

The navbar doesn't let you avoid scrolling all the way up, since these
core doc navigation elements are not inside the navbar. And as such, my
patch does not remove these elements.

As for scrolling up, many browsers recognize the Home key as a shortcut
to scroll to the top. For mobile, at least on iOS, one can do the same
by touching the top of the screen.

> I do see it from your viewpoint and I could argue it that way as well,
> but I'm not convinced yet, and am definitely not convinced on mobile.
> 
> Thanks,
> 
> Jonathan
> 

On 10/19/18 5:50 PM, Andres Freund wrote:
> Hi,
>
> On 2018-10-19 17:37:07 -0400, Jonathan S. Katz wrote:
>>> I don't like the shout box in the docs, FWIW. For me that's reference
>>> material, and I don't want to waste the space. Currently content starts
>>> like half a screen down when at the top. That's a *lot*.
>
> You're quoting me saying things about the shout box - but I think you're
> talking about the fixed navbar?
>

Probably. But I do think we should have the shoutbox there both for
consistency and the fact the majority of our traffic goes to the docs.
The shoutbox does provide a reference for when a new release comes out,
and if vast majority of people are going to pg.org to view our docs, it
provides a nice place to let people know when there are updates.

>
>> Well, the things up top are the core doc navigation (versions, search,
>> TOCs on the page). Those are fairly important, particularly on large
>> pages. And also on large pages, it can be a pain to scroll all the way
>> back up if you need to get to another part of the site, or search.
>
> It's like one swipe to scroll back up even on big pages, I don't quite
> buy that. But I find the mobile header much less intrusive / distracting
> than the non-mobile one (Doesn't change size. Only a small symbol, not
> multiple links), so I don't care as much.
>

I hear you, but still not sold :)

>
> FWIW, the mobile docs view looks kinda bad when you start out. I've
> attached a screenshot from my phone.  The amount of space taken by the
> header, by the shoutbox, by the version selectors (man, that's like 5
> lines), the search box, the docs header, is more than a bit
> disproportional.
>

Yeah, that I do agree with. I think we can do a better job with how we
can do the version scroll. It will only get worse as we introduce more
unsupported versions of PostgreSQL.

For that on mobile, perhaps we can get away with a select dropdown where
on a change event, it goes to that version of the docs?

Thanks,

Jonathan

On 2018-Oct-19, Jonathan S. Katz wrote:

> On 10/19/18 5:50 PM, Andres Freund wrote:

> > You're quoting me saying things about the shout box - but I think you're
> > talking about the fixed navbar?
> 
> Probably. But I do think we should have the shoutbox there both for
> consistency and the fact the majority of our traffic goes to the docs.
> The shoutbox does provide a reference for when a new release comes out,
> and if vast majority of people are going to pg.org to view our docs, it
> provides a nice place to let people know when there are updates.

I too think the doc pages could stand some additional improvement.  I'm
okay with seeing the shoutbox the first dozen pages I visit, but after
that it's annoying, and by the hundredth time I see it it becomes
infuriating.  Why can't I dismiss it?

As for the list of unsupported versions, I'm not sure that its
omnipresence has a lot of value.  Would it work to have a list of
supported versions plus devel (one line -- we could say "Current (11),
10 / 9.6 / 9.5 / 9.4 / 9.3 / 12dev" since it should be pretty obvious
that "12dev" is development), and have a link "other versions" that
shows the rest of the list?

On mobile, I think it would work to have the version selector integrated
in the navbar (which has plenty of space), as another dropdown.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

> On Oct 22, 2018, at 5:07 PM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
>
>> On 2018-Oct-19, Jonathan S. Katz wrote:
>>
>> On 10/19/18 5:50 PM, Andres Freund wrote:
>
>>> You're quoting me saying things about the shout box - but I think you're
>>> talking about the fixed navbar?
>>
>> Probably. But I do think we should have the shoutbox there both for
>> consistency and the fact the majority of our traffic goes to the docs.
>> The shoutbox does provide a reference for when a new release comes out,
>> and if vast majority of people are going to pg.org to view our docs, it
>> provides a nice place to let people know when there are updates.
>
> I too think the doc pages could stand some additional improvement.  I'm
> okay with seeing the shoutbox the first dozen pages I visit, but after
> that it's annoying, and by the hundredth time I see it it becomes
> infuriating.  Why can't I dismiss it?

That’s a good idea. We could store that it has been dismissed in a cookie and then have it
reappear when a new announcement comes out. That should not be too difficult to create a patch
for.


> As for the list of unsupported versions, I'm not sure that its
> omnipresence has a lot of value.  Would it work to have a list of
> supported versions plus devel (one line -- we could say "Current (11),
> 10 / 9.6 / 9.5 / 9.4 / 9.3 / 12dev" since it should be pretty obvious
> that "12dev" is development), and have a link "other versions" that
> shows the rest of the list?

Yeah, and perhaps move the list of unsupported versions to the bottom of the page?

> On mobile, I think it would work to have the version selector integrated
> in the navbar (which has plenty of space), as another dropdown.

Not a bad idea - it may take some work given the nav bar is a global component. Will think on it.

Jonathan

Hi,

On 2018-10-22 13:07:47 -0300, Alvaro Herrera wrote:
> On 2018-Oct-19, Jonathan S. Katz wrote:
> 
> > On 10/19/18 5:50 PM, Andres Freund wrote:
> 
> > > You're quoting me saying things about the shout box - but I think you're
> > > talking about the fixed navbar?
> > 
> > Probably. But I do think we should have the shoutbox there both for
> > consistency and the fact the majority of our traffic goes to the docs.
> > The shoutbox does provide a reference for when a new release comes out,
> > and if vast majority of people are going to pg.org to view our docs, it
> > provides a nice place to let people know when there are updates.
> 
> I too think the doc pages could stand some additional improvement.  I'm
> okay with seeing the shoutbox the first dozen pages I visit, but after
> that it's annoying, and by the hundredth time I see it it becomes
> infuriating.  Why can't I dismiss it?

Yea.

> As for the list of unsupported versions, I'm not sure that its
> omnipresence has a lot of value.  Would it work to have a list of
> supported versions plus devel (one line -- we could say "Current (11),
> 10 / 9.6 / 9.5 / 9.4 / 9.3 / 12dev" since it should be pretty obvious
> that "12dev" is development), and have a link "other versions" that
> shows the rest of the list?

Yea, if it's one line (current choices + dev) with a + or such that
expands to a list of the old versions, it'd be much better than it's
now.

I also wonder why we need to have two search boxes on every page. Can't
we have one where there's a selector for 'docs' and 'whole site'? I
never use the search (grepping sgml is more efficient & accurate), but I
can see why we'd want to offer that. But two boxes seems superfluous.

We currently reference the version we're on two times in as many
lines. Looking at
https://www.postgresql.org/docs/devel/static/intro-whatis.html
- "Documentation → PostgreSQL devel (2018-10-22 16:17:03)"
- underlined "devel"

Greetings,

Andres Freund

Hi Matthijs,

On 10/22/18 7:02 PM, Matthijs van der Vleuten wrote:
>
>
> Meanwhile, could you apply the patch I submitted? It improves usability
> and removes no content. It just unsticks the navigation bar (and fixes
> the shoutbox padding), so that you can see more of the docs at once.

Well, I will at least review the patch, which I have now done ;)

While the patch adjusts the padding on the docs, it breaks across the
rest of the site. Now the shoutbox is missing on every page other than
the documentation, so I do not want to apply this patch.

And again, as I said above, I'm not sold on unsticking the navigation
bar, especially in the case of mobile.

I think the route to go with the shoutbox is Alvaro's suggestion, which
should not take too long to code up.

Thanks,

Jonathan

On 10/22/18 7:11 PM, Andres Freund wrote:
>
> I also wonder why we need to have two search boxes on every page. Can't
> we have one where there's a selector for 'docs' and 'whole site'? I
> never use the search (grepping sgml is more efficient & accurate), but I
> can see why we'd want to offer that. But two boxes seems superfluous.
>

The two boxes was a temporary compromise given we had the search box on
the old docs, but never had a global search until we had the new site.
In other words, yes, it is superfluous and we need to figure it out.

> We currently reference the version we're on two times in as many
> lines. Looking at
> https://www.postgresql.org/docs/devel/static/intro-whatis.html
> - "Documentation → PostgreSQL devel (2018-10-22 16:17:03)"
> - underlined "devel"

Well, those are part of the breadcrumbs. Though browsing through it does
not feel like they are used, so we could eliminate them and get at least
one line back for now.

Thanks,

Jonathan

> On 22 Oct 2018, at 20:48, Jonathan S. Katz <jkatz@postgresql.org> wrote:
> 
> Hi Matthijs,
> 
> On 10/22/18 7:02 PM, Matthijs van der Vleuten wrote:
>> 
>> 
>> Meanwhile, could you apply the patch I submitted? It improves usability
>> and removes no content. It just unsticks the navigation bar (and fixes
>> the shoutbox padding), so that you can see more of the docs at once.
> 
> Well, I will at least review the patch, which I have now done ;)
> 
> While the patch adjusts the padding on the docs, it breaks across the
> rest of the site. Now the shoutbox is missing on every page other than
> the documentation, so I do not want to apply this patch.

Oops, I did not consider that the stylesheet is not exclusively used on
the docs section of the site. Unfortunately I don't see a good way to 
have my changes apply only there.

Personally I wouldn't mind getting rid of the sticky property of the 
navigation bar site-wide, which would solve the issue you've pointed 
out. However, I wouldn't want to impose on the promotional part of the
site and this only really bothers me on the docs. Which is why I 
submitted the patch in the first place :)

In any case, thank you for reviewing the patch.

> And again, as I said above, I'm not sold on unsticking the navigation
> bar, especially in the case of mobile.

Well, as it is, the navigation bar on mobile only contains the logo and
a hamburger menu. It seems quite useless to me to have that stuck to the
top of the screen, especially considering that mobile screens are small.

> I think the route to go with the shoutbox is Alvaro's suggestion, which
> should not take too long to code up.
> 
> Thanks,
> 
> Jonathan
> 

> > > Commit 6679835174a93d5688c649c4feb2604cd6afd2a0 added the site-wide
> > > navigation bar to the docs pages. This navigation bar is stuck to the
> > > top of the browser viewport.
> 
> +1 for removing that, I want to read the docs, not loose a portion of my
> screen to the navbar. That doesn't matter as much in other parts of the
> website, where I'm not going to constantly look at lots of content.

+1 from me as well for "unsticking" the navigation bar. I browse the web
with enlarged fonts, which makes the navigation bar even bigger and more
obtrusive as it covers the content.

Waited for a while to chime in on this thread because I thought for sure
this annoying navbar would be fixed, but since that hasn't happened, I'm
adding my 2¢.

On 2/2/19 8:31 PM, Joe Nelson wrote:
>>>> Commit 6679835174a93d5688c649c4feb2604cd6afd2a0 added the site-wide
>>>> navigation bar to the docs pages. This navigation bar is stuck to the
>>>> top of the browser viewport.
>>
>> +1 for removing that, I want to read the docs, not loose a portion of my
>> screen to the navbar. That doesn't matter as much in other parts of the
>> website, where I'm not going to constantly look at lots of content.
>
> +1 from me as well for "unsticking" the navigation bar. I browse the web
> with enlarged fonts, which makes the navigation bar even bigger and more
> obtrusive as it covers the content.

This is a legitimate concern, thanks for reporting it. When I did some
testing with larger fonts in several views, this appeared to be obtrusive.

>
> Waited for a while to chime in on this thread because I thought for sure
> this annoying navbar would be fixed, but since that hasn't happened, I'm
> adding my 2¢.
>

Attached is a patch that actually corrects the problem. If there are no
objections, I will apply in the next day.

Thanks,

Jonathan

On 2/3/19 9:36 AM, Jonathan S. Katz wrote:
> Attached is a patch that actually corrects the problem. If there are no
> objections, I will apply in the next day.

I have committed the aforementioned patch.

Thank you all for your feedback!

Jonathan

> On 4 Feb 2019, at 16:56, Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> On 2/3/19 9:36 AM, Jonathan S. Katz wrote:
>> Attached is a patch that actually corrects the problem. If there are no
>> objections, I will apply in the next day.
>
> I have committed the aforementioned patch.

Sorry for being too slow to review, but I believe this patch made the navbar
partially overlap the top row of content.

In a desktop size browser the top row is partially obscured, to then be fully
visible when the navbar becomes a hamburger, to be fully overlapped when the
searchbox disappears to finally be visible again at < 640 wide displays when
the shoutbox seeminly erroneously reappears (it’s mostly hidden but pushes the
content down).

I haven’t had time to try and fix it properly, but removing the shoutbox from
the docs instead of hiding it underneath the navbar, and adding padding-top:
1.5rem; to the main content seems to fix it for all viewports (only tested in
Chrome).

cheers ./daniel

On 2/5/19 5:33 AM, Daniel Gustafsson wrote:
>> On 4 Feb 2019, at 16:56, Jonathan S. Katz <jkatz@postgresql.org> wrote:
>>
>> On 2/3/19 9:36 AM, Jonathan S. Katz wrote:
>>> Attached is a patch that actually corrects the problem. If there are no
>>> objections, I will apply in the next day.
>>
>> I have committed the aforementioned patch.
>
> Sorry for being too slow to review, but I believe this patch made the navbar
> partially overlap the top row of content.

Specifically, this is in the docs. I was able to reproduce it. When I
had tested this, I did not have that issue, but perhaps I missed it
cause of local browser cache. Oops :(

>
> In a desktop size browser the top row is partially obscured, to then be fully
> visible when the navbar becomes a hamburger, to be fully overlapped when the
> searchbox disappears to finally be visible again at < 640 wide displays when
> the shoutbox seeminly erroneously reappears (it’s mostly hidden but pushes the
> content down).
>
> I haven’t had time to try and fix it properly, but removing the shoutbox from
> the docs instead of hiding it underneath the navbar, and adding padding-top:
> 1.5rem; to the main content seems to fix it for all viewports (only tested in
> Chrome).

I'll investigate and work on getting a patch ready for today.

Thanks,

Jonathan

> On 5 Feb 2019, at 18:27, Jonathan S. Katz <jkatz@postgresql.org> wrote:

> Specifically, this is in the docs.

Correct, this is in the docs and only in the docs.

cheers ./daniel