Proposed HTML Documentation Styles

classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

Proposed HTML Documentation Styles

Jonathan S. Katz-3
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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Pavel Stehule


čt 4. 10. 2018 v 17:50 odesílatel Jonathan S. Katz <[hidden email]> napsal:
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

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



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

Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Alvaro Herrera-9
On 2018-Oct-04, Pavel Stehule wrote:

> čt 4. 10. 2018 v 17:50 odesílatel Jonathan S. Katz <[hidden email]>
> napsal:
>
> 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.

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

Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Jonathan S. Katz-3
In reply to this post by Pavel Stehule
Hi Pavel,

On 10/4/18 12:02 PM, Pavel Stehule wrote:

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

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

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

Thanks for your feedback!

Jonathan


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Jonathan S. Katz-3
In reply to this post by Alvaro Herrera-9
On 10/4/18 12:28 PM, Alvaro Herrera wrote:

> On 2018-Oct-04, Pavel Stehule wrote:
>
>> čt 4. 10. 2018 v 17:50 odesílatel Jonathan S. Katz <[hidden email]>
>> napsal:
>>
>> 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.
>
> 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.
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.

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

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

Jonathan


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Daniel Gustafsson
> On 4 Oct 2018, at 18:33, Jonathan S. Katz <[hidden email]> wrote:
>
> On 10/4/18 12:28 PM, Alvaro Herrera wrote:

>> 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.
>
> 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
Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Dean Rasheed-3
In reply to this post by Jonathan S. Katz-3
On Thu, 4 Oct 2018 at 16:50, Jonathan S. Katz <[hidden email]> wrote:

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

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

Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Jonathan S. Katz-3
In reply to this post by Jonathan S. Katz-3
On 10/4/18 12:33 PM, Jonathan S. Katz wrote:

> On 10/4/18 12:28 PM, Alvaro Herrera wrote:
>> 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.
>
> 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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Jonathan S. Katz-3
In reply to this post by Dean Rasheed-3
Hi Dean,

On 10/4/18 3:41 PM, Dean Rasheed wrote:

> On Thu, 4 Oct 2018 at 16:50, Jonathan S. Katz <[hidden email]> wrote:
>> 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.
>>
>> 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
>>
>
> 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.
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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Dean Rasheed-3
On Tue, 9 Oct 2018, 02:38 Jonathan S. Katz, <[hidden email]> wrote:
Hi Dean,

On 10/4/18 3:41 PM, Dean Rasheed wrote:
> On Thu, 4 Oct 2018 at 16:50, Jonathan S. Katz <[hidden email]> wrote:
>> 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.
>>
>> 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
>>
>
> 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.

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

Screenshot_20181011-062959.png (340K) Download Attachment
Screenshot_20181011-062840.png (612K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Dean Rasheed-3
On Thu, 11 Oct 2018 at 06:49, Dean Rasheed <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Jonathan S. Katz-3
Hi Dean,

On 10/11/18 3:01 AM, Dean Rasheed wrote:
> On Thu, 11 Oct 2018 at 06:49, Dean Rasheed <[hidden email]> 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.

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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Dean Rasheed-3
On Fri, 12 Oct 2018 at 03:03, Jonathan S. Katz <[hidden email]> wrote:

> On 10/11/18 3:01 AM, Dean Rasheed wrote:
> > On Thu, 11 Oct 2018 at 06:49, Dean Rasheed <[hidden email]> 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.
>
> 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.
>

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

Reply | Threaded
Open this post in threaded view
|

Re: Proposed HTML Documentation Styles

Jonathan S. Katz-3
In reply to this post by Jonathan S. Katz-3
On 10/4/18 11:50 AM, Jonathan S. Katz wrote:

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


signature.asc (849 bytes) Download Attachment