pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedUsability ideas: text width and headers that are links
5+ messages / 4 participants
[nested] [flat]
* Usability ideas: text width and headers that are links
@ 2022-10-21 13:54 Niels Bom <niels@nielsbom.com>
2022-10-21 15:42 ` Re: Usability ideas: text width and headers that are links Jonathan S. Katz <jkatz@postgresql.org>
0 siblings, 1 reply; 5+ messages in thread
From: Niels Bom @ 2022-10-21 13:54 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Hi!
I have 2 small ideas to improve the usability of the PostgreSQL documentation. I'm looking at v15 (1) mostly.
Idea 1:
Give the text width of the main content a max width.
Idea 2:
Each h3 and h4 element should be a link pointing to the nearest parent section with an id. This makes deeplinking to specific parts of a page easier. This prevents people from having to scroll to the top, find out which table-of-content-link they have to click to get the deeplink of where they wanted to link. This is actually quite a common pattern. See the Python docs (2) and the Mozilla docs (3) as examples. The pattern on those sites is even a little nicer by showing an icon on hover.
I've created a user script (4) to do this in my browser. You can test it with the Tampermonkey browser extension.
I'd <3 to hear your thoughts.
Cheers,
Niels
1: https://www.postgresql.org/docs/15/index.html
2: https://docs.python.org/3/library/stdtypes.html#dictionary-view-objects
3: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce#descri...
4: https://github.com/nielsbom/tampermonkey_scripts/blob/main/scripts/postgresql.org.js
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Usability ideas: text width and headers that are links
2022-10-21 13:54 Usability ideas: text width and headers that are links Niels Bom <niels@nielsbom.com>
@ 2022-10-21 15:42 ` Jonathan S. Katz <jkatz@postgresql.org>
2022-10-21 16:49 ` Re: Usability ideas: text width and headers that are links Niels Bom <niels@nielsbom.com>
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan S. Katz @ 2022-10-21 15:42 UTC (permalink / raw)
To: Niels Bom <niels@nielsbom.com>; pgsql-docs@lists.postgresql.org
Hi,
Thanks for the suggestions. Comments inline:
On 10/21/22 9:54 AM, Niels Bom wrote:
> Hi!
>
> I have 2 small ideas to improve the usability of the PostgreSQL documentation. I'm looking at v15 (1) mostly.
>
> Idea 1:
> Give the text width of the main content a max width.
Why? Can you please provide examples? Screenshots are OK.
> Idea 2:
> Each h3 and h4 element should be a link pointing to the nearest parent section with an id. This makes deeplinking to specific parts of a page easier. This prevents people from having to scroll to the top, find out which table-of-content-link they have to click to get the deeplink of where they wanted to link. This is actually quite a common pattern. See the Python docs (2) and the Mozilla docs (3) as examples. The pattern on those sites is even a little nicer by showing an icon on hover.
This has been on my backlog for awhile, i.e. to have the hovering
"anchor holders". I'll try to move it up on the list.
Thanks,
Jonathan
Attachments:
[application/pgp-signature] OpenPGP_signature (839B, ../../283a08f1-ae00-8a96-db7c-dbd43bb53aae@postgresql.org/2-OpenPGP_signature)
download
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Usability ideas: text width and headers that are links
2022-10-21 13:54 Usability ideas: text width and headers that are links Niels Bom <niels@nielsbom.com>
2022-10-21 15:42 ` Re: Usability ideas: text width and headers that are links Jonathan S. Katz <jkatz@postgresql.org>
@ 2022-10-21 16:49 ` Niels Bom <niels@nielsbom.com>
2022-11-07 09:41 ` Re: Usability ideas: text width and headers that are links Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 1 reply; 5+ messages in thread
From: Niels Bom @ 2022-10-21 16:49 UTC (permalink / raw)
To: Jonathan S. Katz <jkatz@postgresql.org>; pgsql-docs@lists.postgresql.org
On Fri, Oct 21, 2022, at 17:42, Jonathan S. Katz wrote:
> Hi,
>
> Thanks for the suggestions. Comments inline:
>
> On 10/21/22 9:54 AM, Niels Bom wrote:
>> Hi!
>>
>> I have 2 small ideas to improve the usability of the PostgreSQL documentation. I'm looking at v15 (1) mostly.
>>
>> Idea 1:
>> Give the text width of the main content a max width.
>
> Why? Can you please provide examples? Screenshots are OK.
Setting a max-width on regular textual content is good for readability, which in turn increases accessibility. See this W3C a11y documentation (1) and an a11y page by the US government (2) for more detailed info.
Using the CSS max-width property makes narrower sizes possible (for smaller screens) but sets an upper limit. The newer `ch` unit in CSS is a good-enough approximation of the average width of a character. I've seen 66ch as the "ideal" width for regular text. For the docs code examples need to have enough width too of course. But we can have those be wider than their containing element if need be.
1: https://www.w3.org/WAI/tutorials/page-structure/styling/
2: https://accessibility.digital.gov/visual-design/typography/
>
>> Idea 2:
>> Each h3 and h4 element should be a link pointing to the nearest parent section with an id. This makes deeplinking to specific parts of a page easier. This prevents people from having to scroll to the top, find out which table-of-content-link they have to click to get the deeplink of where they wanted to link. This is actually quite a common pattern. See the Python docs (2) and the Mozilla docs (3) as examples. The pattern on those sites is even a little nicer by showing an icon on hover.
>
> This has been on my backlog for awhile, i.e. to have the hovering
> "anchor holders". I'll try to move it up on the list.
Cool! I could help if you want to.
>
> Thanks,
>
> Jonathan
>
>
> Attachments:
> * OpenPGP_signature
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Usability ideas: text width and headers that are links
2022-10-21 13:54 Usability ideas: text width and headers that are links Niels Bom <niels@nielsbom.com>
2022-10-21 15:42 ` Re: Usability ideas: text width and headers that are links Jonathan S. Katz <jkatz@postgresql.org>
2022-10-21 16:49 ` Re: Usability ideas: text width and headers that are links Niels Bom <niels@nielsbom.com>
@ 2022-11-07 09:41 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-11-09 05:52 ` Re: Usability ideas: text width and headers that are links Maciek Sakrejda <m.sakrejda@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Alvaro Herrera @ 2022-11-07 09:41 UTC (permalink / raw)
To: Niels Bom <niels@nielsbom.com>; +Cc: Jonathan S. Katz <jkatz@postgresql.org>; pgsql-docs@lists.postgresql.org
On 2022-Oct-21, Niels Bom wrote:
> Setting a max-width on regular textual content is good for
> readability, which in turn increases accessibility. See this W3C a11y
> documentation (1) and an a11y page by the US government (2) for more
> detailed info.
>
> Using the CSS max-width property makes narrower sizes possible (for
> smaller screens) but sets an upper limit. The newer `ch` unit in CSS
> is a good-enough approximation of the average width of a character.
> I've seen 66ch as the "ideal" width for regular text. For the docs
> code examples need to have enough width too of course. But we can have
> those be wider than their containing element if need be.
+1 for this idea. (I often open multiple windows just so that I end up
with the right width in the one containing text to read, as a substitute
for this.)
This should definitely only apply to running text, not code examples,
synopses, tables, etc; otherwise it's going to be *very* bothersome.
--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
#error "Operator lives in the wrong universe"
("Use of cookies in real-time system development", M. Gleixner, M. Mc Guire)
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Usability ideas: text width and headers that are links
2022-10-21 13:54 Usability ideas: text width and headers that are links Niels Bom <niels@nielsbom.com>
2022-10-21 15:42 ` Re: Usability ideas: text width and headers that are links Jonathan S. Katz <jkatz@postgresql.org>
2022-10-21 16:49 ` Re: Usability ideas: text width and headers that are links Niels Bom <niels@nielsbom.com>
2022-11-07 09:41 ` Re: Usability ideas: text width and headers that are links Alvaro Herrera <alvherre@alvh.no-ip.org>
@ 2022-11-09 05:52 ` Maciek Sakrejda <m.sakrejda@gmail.com>
0 siblings, 0 replies; 5+ messages in thread
From: Maciek Sakrejda @ 2022-11-09 05:52 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Niels Bom <niels@nielsbom.com>; Jonathan S. Katz <jkatz@postgresql.org>; pgsql-docs@lists.postgresql.org
On Mon, Nov 7, 2022 at 1:41 AM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
> On 2022-Oct-21, Niels Bom wrote:
> > Setting a max-width on regular textual content is good for
> > readability, which in turn increases accessibility. See this W3C a11y
> > documentation (1) and an a11y page by the US government (2) for more
> > detailed info.
> >
> > Using the CSS max-width property makes narrower sizes possible (for
> > smaller screens) but sets an upper limit. The newer `ch` unit in CSS
> > is a good-enough approximation of the average width of a character.
> > I've seen 66ch as the "ideal" width for regular text. For the docs
> > code examples need to have enough width too of course. But we can have
> > those be wider than their containing element if need be.
>
> +1 for this idea. (I often open multiple windows just so that I end up
> with the right width in the one containing text to read, as a substitute
> for this.)
For what it's worth, I've also often wished for a max-width on the
docs. Another +1.
66ch ends up rather stark, though: I think we should go with something
considerably wider.
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2022-11-09 05:52 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-10-21 13:54 Usability ideas: text width and headers that are links Niels Bom <niels@nielsbom.com>
2022-10-21 15:42 ` Jonathan S. Katz <jkatz@postgresql.org>
2022-10-21 16:49 ` Niels Bom <niels@nielsbom.com>
2022-11-07 09:41 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2022-11-09 05:52 ` Maciek Sakrejda <m.sakrejda@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox