Subject: Proposed HTML Documentation Styles

From: "Jonathan S. Katz" <[email-masked]>
Date: Thu, 4 Oct 2018 11:50:26 -0400

Hi,

As part of the effort to modernize the look and feel of PostgreSQL.org
and associated web projects, Sarah & I have worked on applying the new
styles to the documentation. The main goals of the project were:

- To have the documentation styles match that of the main website
- To make the documentation easier to view on mobile devices
- To set up the web-based documentation for future usability changes and
improvements

Other than reversing how the versions are display at the top of the
website, we did not change any of the documentation structure and do not
intend to as part of this version of the project.

We have created a prototype of the new styles that can be viewed here,
with the credentials below:

	http://174.138.60.30/docs/
	pgdocs / newstyles

When browsing through this site, please note:

- All interactions are confined to the "/docs" folder
- Not all of the docs are loaded and they are not all the latest
versions - this is just for beta testing purposes
- Search in the prototype does not work

We are looking for feedback in the following areas:

- Things that may have degraded the user experience, e.g. things that
are difficult to read
- Visual bugs and errors

Our goal is to launch these changes with the upcoming major release, so
we appreciate your diligence in providing helpful feedback so we can
provide the best possible experience.

Thanks,

Jonathan

---

From: Pavel Stehule <[email-masked]>
Date: Thu, 4 Oct 2018 18:02:48 +0200

> - Things that may have degraded the user experience, e.g. things that

When I am going to document, then I see (about 0.5 sec) big PostgreSQL
logo. It is not pleasant effect.

I don't like table style - middle vertical line is too black

Used colour palette is maybe too red based.

All my notes are subjective, just my feeling

Regards

Pavel

---

From: Alvaro Herrera <[email-masked]>
Date: Thu, 4 Oct 2018 13:28:30 -0300

> Used colour palette is maybe too red based.

Yeah, it's heavily red and I didn't like that very much either, though I
can live with it if everyone else loves it.

This TOC looks a bit odd, with those bold black elements amongst all
that red: http://174.138.60.30/docs/10/static/ecpg.html  I suppose these
should just be bold without changing the color.

This page http://174.138.60.30/docs/9.4/static/libpq-connect.html
has some keywords inside "Warning" and "Note" boxes. Those keywords
acquire a gray background instead of inheriting the background color of
the box, as in the original stylesheets.  Really odd-looking.

Cheers

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

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Thu, 4 Oct 2018 12:31:55 -0400

Hi Pavel,

> logo. It is not pleasant effect.

That's cache related - we won't need to worry about that on the
production site.

> All my notes are subjective, just my feeling

Thanks for your feedback!

Jonathan

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Thu, 4 Oct 2018 12:33:59 -0400

> can live with it if everyone else loves it.

We can always see if we can find something more palatable. In some
earlier testing there were some issues with the blue, but perhaps there
are some better ways to achieve the proper PostgreSQL color palette.

> the box, as in the original stylesheets.  Really odd-looking.

Thanks - both of the above have been noted and will be fixed.

Jonathan

---

From: Daniel Gustafsson <[email-masked]>
Date: Thu, 4 Oct 2018 20:23:43 +0200

> On 4 Oct 2018, at 18:33, Jonathan S. Katz <[email-masked]> wrote:
> 

> Thanks - both of the above have been noted and will be fixed.

Not sure if it’s the same thing, but code blocks on Tip boxes no longer have a
separate background color - only an outline.  There is an example on the below
page:

	http://174.138.60.30/docs/11/static/functions-matching.html

cheers ./daniel

---

From: Dean Rasheed <[email-masked]>
Date: Thu, 4 Oct 2018 20:41:09 +0100

On Thu, 4 Oct 2018 at 16:50, Jonathan S. Katz <[email-masked]> wrote:
> styles to the documentation.
>

There seems to be a problem with the layout some of the tables. For
example on this page:

http://174.138.60.30/docs/10/static/functions-math.html

the description column is far too narrow, leading to descriptions with
one or two words per line, spread over dozens of lines.

Regards,
Dean

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Thu, 4 Oct 2018 18:33:07 -0400

> Thanks - both of the above have been noted and will be fixed.

Updates for this have been pushed to the test website. Thanks for reporting!

Jonathan

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Mon, 8 Oct 2018 21:38:24 -0400

Hi Dean,

> one or two words per line, spread over dozens of lines.

Sorry for the slow reply on this one - it took a little bit more time to
troubleshoot. This should now be fixed - please let me know if you are
still having issues.

Thanks,

Jonathan

---

From: Dean Rasheed <[email-masked]>
Date: Thu, 11 Oct 2018 06:49:57 +0100

> troubleshoot. This should now be fixed - please let me know if you are
Thanks. That definitely improves things from a normal desktop browser.
However, this still isn't ideal on smaller screens. For example, attached
are screenshots taken from my Android tablet of the bottom of Table 9.5,
comparing the current docs with the new ones.

Regards,
Dean

---

From: Dean Rasheed <[email-masked]>
Date: Thu, 11 Oct 2018 08:01:02 +0100

On Thu, 11 Oct 2018 at 06:49, Dean Rasheed <[email-masked]> wrote:
> For example, attached are screenshots taken from my Android tablet

For the record, that was a Samsung Galaxy Tab S2 8.0, with a screen
resolution of 2048x1536 and a device pixel ratio of 2.0, I think. So
the logical resolution is 1024x768, and in portrait mode, the logical
width is 768 pixels.

Regards,
Dean

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Thu, 11 Oct 2018 22:03:34 -0400

Hi Dean,

> the logical resolution is 1024x768, and in portrait mode, the logical

Unfortunately HTML tables are not great in mobile web. With that said,
we pushed up a change that should keep them from exploding as much to
the right. We've also bumped up the font-size slightly from the current
site so they could be slightly easier to read.

(Note: when testing in the browser, they appear to be illegible unless
you have super vision, but when on an actual device they are legible).

There is only so much we can do now without redesigning how the tables
are assembled.

Thanks again for your feedback!

Best,

Jonathan

---

From: Dean Rasheed <[email-masked]>
Date: Sun, 14 Oct 2018 11:49:35 +0100

> There is only so much we can do now without redesigning how the tables

Indeed. It's probably unrealistic to try to support really small
devices. I mentioned that particular one because there was a clear
regression from the old style. I have re-tested it and now it's much
better, so thanks for the fix.

Arguably, the font scaling in the @media CSS is now a little too
aggressive. IMO 60% rather than 50% is a little more readable for the
576-768px range, and 80% rather than 70% for the 769-992px range, but
that's a very subjective matter.

Regards,
Dean

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Tue, 16 Oct 2018 10:44:45 -0400

> - To set up the web-based documentation for future usability changes and

Thank you everyone for your feedback. We launched the new documentation
styles this morning. Please let us know if you find any issues or have
any additional feedback.

Thanks,

Jonathan

---

From: Liudmila Mantrova <[email-masked]>
Date: Mon, 22 Oct 2018 19:14:36 +0300

> styles this morning. Please let us know if you find any issues or have
Hi Jonathan,

Thank you for modernizing doc styles!

I have noticed a small rendering issue in the Chrome browser. If you 
follow a link to a bookmark in a different page, it's hidden below the 
website header. Links within the same page and section-level links 
appear to work fine.

The attached screenshot illustrates the result of navigating to the 
default_statistics_targetdescription from the 
https://www.postgresql.org/docs/10/static/planner-stats.html page.

I have not tested this thoroughly, but I got the same result on my 
smartphone in Safari, while having no issues at all in Firefox on Ubuntu.

-- 
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company

---

From: Alvaro Herrera <[email-masked]>
Date: Mon, 22 Oct 2018 13:29:49 -0300

On 2018-Oct-22, Liudmila Mantrova wrote:

> I have noticed a small rendering issue in the Chrome browser. If you follow
> a link to a bookmark in a different page, it's hidden below the website
> header. Links within the same page and section-level links appear to work
> fine.

Yeah, I see this effect too and it's very confusing.

---

From: James Cloos <[email-masked]>
Date: Tue, 23 Oct 2018 18:02:15 -0400

[Catching up on pg lists.]

When I view any doc page now, before seeing the page, a huge rendering
of the logo appears; it is then replaced with the actual page.

Perhaps the pages should use a smaller png than the 900x928 is now does?

-JimC
-- 
James Cloos <[email-masked]>         OpenPGP: 0x997A9F17ED7DAEA6