New "function tables" in V13 documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
29 messages Options
12
Reply | Threaded
Open this post in threaded view
|

New "function tables" in V13 documentation

Thomas Kellerer-4
In case someone is interested: there is a little discussion going on on Reddit whether the new format of presenting functions in V13 is a step backwards:

   https://www.reddit.com/r/PostgreSQL/comments/jpi0rp/does_anyone_else_feel_like_the_v13_docs_are_a/

Thomas


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Adrian Klaver-4
On 11/8/20 1:57 PM, Thomas Kellerer wrote:
> In case someone is interested: there is a little discussion going on on
> Reddit whether the new format of presenting functions in V13 is a step
> backwards:
>
>    
> https://www.reddit.com/r/PostgreSQL/comments/jpi0rp/does_anyone_else_feel_like_the_v13_docs_are_a/ 

Yeah, I would agree with the mobile first design comments. Then again
that plague is hitting most sites these days. My 2 cents is it is a step
backwards. You can cover more ground quickly and digest it faster in the
old format.

>
>
> Thomas
>
>


--
Adrian Klaver
[hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Tony Shelver

On Mon, 9 Nov 2020 at 02:54, Adrian Klaver <[hidden email]> wrote:
On 11/8/20 1:57 PM, Thomas Kellerer wrote:
> In case someone is interested: there is a little discussion going on on
> Reddit whether the new format of presenting functions in V13 is a step
> backwards:
>
>   
> https://www.reddit.com/r/PostgreSQL/comments/jpi0rp/does_anyone_else_feel_like_the_v13_docs_are_a/

Yeah, I would agree with the mobile first design comments. Then again
that plague is hitting most sites these days. My 2 cents is it is a step
backwards. You can cover more ground quickly and digest it faster in the
old format.

>
>
> Thomas
>
>


--
Adrian Klaver
[hidden email]

Agreed, old format much more readable.
Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Álvaro Herrera
In reply to this post by Adrian Klaver-4
On 2020-Nov-08, Adrian Klaver wrote:

> On 11/8/20 1:57 PM, Thomas Kellerer wrote:
> > In case someone is interested: there is a little discussion going on on
> > Reddit whether the new format of presenting functions in V13 is a step
> > backwards:
> >
> >     https://www.reddit.com/r/PostgreSQL/comments/jpi0rp/does_anyone_else_feel_like_the_v13_docs_are_a/
>
> Yeah, I would agree with the mobile first design comments. Then again that
> plague is hitting most sites these days. My 2 cents is it is a step
> backwards. You can cover more ground quickly and digest it faster in the old
> format.

The person who made that comment retracted later.

If you have suggestion on how to improve the new format, I'm sure we can
discuss that.  It seems pretty clear to me that we're not going back to
the old format.


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Adrian Klaver-4
On 11/9/20 12:06 PM, Alvaro Herrera wrote:

> On 2020-Nov-08, Adrian Klaver wrote:
>
>> On 11/8/20 1:57 PM, Thomas Kellerer wrote:
>>> In case someone is interested: there is a little discussion going on on
>>> Reddit whether the new format of presenting functions in V13 is a step
>>> backwards:
>>>
>>>      https://www.reddit.com/r/PostgreSQL/comments/jpi0rp/does_anyone_else_feel_like_the_v13_docs_are_a/
>>
>> Yeah, I would agree with the mobile first design comments. Then again that
>> plague is hitting most sites these days. My 2 cents is it is a step
>> backwards. You can cover more ground quickly and digest it faster in the old
>> format.
>
> The person who made that comment retracted later.
>
> If you have suggestion on how to improve the new format, I'm sure we can
> discuss that.  It seems pretty clear to me that we're not going back to
> the old format.

Improve it by going back to old format. Not sure why that is not open to
discussion?


--
Adrian Klaver
[hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Álvaro Herrera
On 2020-Nov-09, Adrian Klaver wrote:

> > If you have suggestion on how to improve the new format, I'm sure we can
> > discuss that.  It seems pretty clear to me that we're not going back to
> > the old format.
>
> Improve it by going back to old format. Not sure why that is not open to
> discussion?

Because the old format had problems.


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

David G Johnston
In reply to this post by Adrian Klaver-4
On Mon, Nov 9, 2020 at 1:33 PM Adrian Klaver <[hidden email]> wrote:
On 11/9/20 12:06 PM, Alvaro Herrera wrote:

> If you have suggestion on how to improve the new format, I'm sure we can
> discuss that.  It seems pretty clear to me that we're not going back to
> the old format.

Improve it by going back to old format. Not sure why that is not open to
discussion?

More usefully, the current format and content changes are not going to be "reverted" so "going back" is not really an option.  If you want to propose a patch for moving forward to a new format that is similar to the old one while retaining the content changes that would be a possible way forward.

David J.
Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Josef Šimánek
In reply to this post by Álvaro Herrera
po 9. 11. 2020 v 21:35 odesílatel Alvaro Herrera
<[hidden email]> napsal:

>
> On 2020-Nov-09, Adrian Klaver wrote:
>
> > > If you have suggestion on how to improve the new format, I'm sure we can
> > > discuss that.  It seems pretty clear to me that we're not going back to
> > > the old format.
> >
> > Improve it by going back to old format. Not sure why that is not open to
> > discussion?
>
> Because the old format had problems.

The new format has problems as well. I was thinking about reviving old
format conditionally (based on css media queries) to wide screens, and
use current format on mobile-like screen widths.

But it is not clear for me what exactly was the problem with the old
format. Is there any discussion anyone can point me to to ensure I'll
not just revive the old problems, but improve the overall situation?

>
>


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Tom Lane-2
In reply to this post by Álvaro Herrera
Alvaro Herrera <[hidden email]> writes:
> On 2020-Nov-08, Adrian Klaver wrote:
>> Yeah, I would agree with the mobile first design comments. Then again that
>> plague is hitting most sites these days. My 2 cents is it is a step
>> backwards. You can cover more ground quickly and digest it faster in the old
>> format.

> The person who made that comment retracted later.

> If you have suggestion on how to improve the new format, I'm sure we can
> discuss that.  It seems pretty clear to me that we're not going back to
> the old format.

I think there's no question that the new format is better in any case
where a function needs more than a couple words of documentation.
I could see the argument for adopting a more compact format for tables
that contain no such functions.  I think you might find that the set of
such tables is nigh empty, though; even section 9.3 (mathematical
functions) has a lot of functions that need a sentence or two.  We used
to either omit important details for such functions or stick them in
footnotes, and neither of those options is very nice.

                        regards, tom lane


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

David G Johnston
On Mon, Nov 9, 2020 at 1:41 PM Tom Lane <[hidden email]> wrote:
Alvaro Herrera <[hidden email]> writes:
> On 2020-Nov-08, Adrian Klaver wrote:
>> Yeah, I would agree with the mobile first design comments. Then again that
>> plague is hitting most sites these days. My 2 cents is it is a step
>> backwards. You can cover more ground quickly and digest it faster in the old
>> format.

> The person who made that comment retracted later.

> If you have suggestion on how to improve the new format, I'm sure we can
> discuss that.  It seems pretty clear to me that we're not going back to
> the old format.

I think there's no question that the new format is better in any case
where a function needs more than a couple words of documentation.
I could see the argument for adopting a more compact format for tables
that contain no such functions.  I think you might find that the set of
such tables is nigh empty, though; even section 9.3 (mathematical
functions) has a lot of functions that need a sentence or two.  We used
to either omit important details for such functions or stick them in
footnotes, and neither of those options is very nice.

My observation is that the new format reduces one's ability to quickly skim the table to find out what is present since there is considerable extra information in one's eyes during that process that needs to be skimmed over.

My suggestion is to add a "table of contents" at the top of non-trivial sections that simply lists available functions by name (generally ignoring argument variations) and a quick one line description of purpose.  Once a person finds the name of the function that suits their needs they can then reference the main table for details, warnings, and examples.

David J.

Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Adrian Klaver-4
In reply to this post by Álvaro Herrera
On 11/9/20 12:35 PM, Alvaro Herrera wrote:

> On 2020-Nov-09, Adrian Klaver wrote:
>
>>> If you have suggestion on how to improve the new format, I'm sure we can
>>> discuss that.  It seems pretty clear to me that we're not going back to
>>> the old format.
>>
>> Improve it by going back to old format. Not sure why that is not open to
>> discussion?
>
> Because the old format had problems.

That reply is about as useful as the 'improvements'.


--
Adrian Klaver
[hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Tom Lane-2
In reply to this post by Josef Šimánek
=?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <[hidden email]> writes:
> But it is not clear for me what exactly was the problem with the old
> format. Is there any discussion anyone can point me to to ensure I'll
> not just revive the old problems, but improve the overall situation?

The primary discussion threads for this change were

https://www.postgresql.org/message-id/flat/9326.1581457869%40sss.pgh.pa.us

https://www.postgresql.org/message-id/flat/8691.1586798003%40sss.pgh.pa.us

There are a lot of older threads about content (not layout) deficiencies
in our docs that were practically impossible to fix under the old format;
here's one:

https://www.postgresql.org/message-id/flat/158110996889.1089.4224139874633222837%40wrigleys.postgresql.org

                        regards, tom lane


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Ron-2
In reply to this post by David G Johnston
On 11/9/20 2:47 PM, David G. Johnston wrote:
On Mon, Nov 9, 2020 at 1:41 PM Tom Lane <[hidden email]> wrote:
Alvaro Herrera <[hidden email]> writes:
> On 2020-Nov-08, Adrian Klaver wrote:
>> Yeah, I would agree with the mobile first design comments. Then again that
>> plague is hitting most sites these days. My 2 cents is it is a step
>> backwards. You can cover more ground quickly and digest it faster in the old
>> format.

> The person who made that comment retracted later.

> If you have suggestion on how to improve the new format, I'm sure we can
> discuss that.  It seems pretty clear to me that we're not going back to
> the old format.

I think there's no question that the new format is better in any case
where a function needs more than a couple words of documentation.
I could see the argument for adopting a more compact format for tables
that contain no such functions.  I think you might find that the set of
such tables is nigh empty, though; even section 9.3 (mathematical
functions) has a lot of functions that need a sentence or two.  We used
to either omit important details for such functions or stick them in
footnotes, and neither of those options is very nice.

My observation is that the new format reduces one's ability to quickly skim the table to find out what is present since there is considerable extra information in one's eyes during that process that needs to be skimmed over.

My suggestion is to add a "table of contents" at the top of non-trivial sections that simply lists available functions by name (generally ignoring argument variations) and a quick one line description of purpose.  Once a person finds the name of the function that suits their needs they can then reference the main table for details, warnings, and examples.

This is what TOCs are for, no?

--
Angular momentum makes the world go 'round.
Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

David G Johnston
On Mon, Nov 9, 2020 at 2:01 PM Ron <[hidden email]> wrote:
My suggestion is to add a "table of contents" at the top of non-trivial sections that simply lists available functions by name (generally ignoring argument variations) and a quick one line description of purpose.  Once a person finds the name of the function that suits their needs they can then reference the main table for details, warnings, and examples.

This is what TOCs are for, no?


Are you criticizing my over-explanation of the phrase "table of contents" here?

David J.

Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Ron-2
On 11/9/20 3:05 PM, David G. Johnston wrote:
On Mon, Nov 9, 2020 at 2:01 PM Ron <[hidden email]> wrote:
My suggestion is to add a "table of contents" at the top of non-trivial sections that simply lists available functions by name (generally ignoring argument variations) and a quick one line description of purpose.  Once a person finds the name of the function that suits their needs they can then reference the main table for details, warnings, and examples.

This is what TOCs are for, no?


Are you criticizing my over-explanation of the phrase "table of contents" here?

Why do you think that?

I'm agreeing this is why TOCs were invented.


--
Angular momentum makes the world go 'round.
Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

David G Johnston
On Mon, Nov 9, 2020 at 3:30 PM Ron <[hidden email]> wrote:
On 11/9/20 3:05 PM, David G. Johnston wrote:
On Mon, Nov 9, 2020 at 2:01 PM Ron <[hidden email]> wrote:
My suggestion is to add a "table of contents" at the top of non-trivial sections that simply lists available functions by name (generally ignoring argument variations) and a quick one line description of purpose.  Once a person finds the name of the function that suits their needs they can then reference the main table for details, warnings, and examples.

This is what TOCs are for, no?


Are you criticizing my over-explanation of the phrase "table of contents" here?

Why do you think that?

I'm agreeing this is why TOCs were invented.


Because agreement without elaboration usually just merits a +1 so I read more into the statement than you intended.

David J.
Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Merlin Moncure-2
In reply to this post by Thomas Kellerer-4
On Sun, Nov 8, 2020 at 3:57 PM Thomas Kellerer <[hidden email]> wrote:
>
> In case someone is interested: there is a little discussion going on on Reddit whether the new format of presenting functions in V13 is a step backwards:
>
>    https://www.reddit.com/r/PostgreSQL/comments/jpi0rp/does_anyone_else_feel_like_the_v13_docs_are_a/

It's more than a little ironic that reddit's "old" format (still
visible via old.reddit.com) is objectively clearer and better along
exactly the same lines.

merlin


Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

Bruce Momjian
On Mon, Nov  9, 2020 at 07:46:21PM -0600, Merlin Moncure wrote:
> On Sun, Nov 8, 2020 at 3:57 PM Thomas Kellerer <[hidden email]> wrote:
> >
> > In case someone is interested: there is a little discussion going on on Reddit whether the new format of presenting functions in V13 is a step backwards:
> >
> >    https://www.reddit.com/r/PostgreSQL/comments/jpi0rp/does_anyone_else_feel_like_the_v13_docs_are_a/
>
> It's more than a little ironic that reddit's "old" format (still
> visible via old.reddit.com) is objectively clearer and better along
> exactly the same lines.

I think it is funny that the Redit thread thinks we made the format
change because of mobile, but it was actually more for PDF output, which
is more old-school than even web pages.

--
  Bruce Momjian  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee



Reply | Threaded
Open this post in threaded view
|

RE: New "function tables" in V13 documentation

Kevin Brannen
In reply to this post by David G Johnston
>From: David G. Johnston <[hidden email]>

>On Mon, Nov 9, 2020 at 1:41 PM Tom Lane <mailto:[hidden email]> wrote:
>Alvaro Herrera <mailto:[hidden email]> writes:
>> On 2020-Nov-08, Adrian Klaver wrote:
>>> Yeah, I would agree with the mobile first design comments. Then again that
>>> plague is hitting most sites these days. My 2 cents is it is a step
>>> backwards. You can cover more ground quickly and digest it faster in the old
>>> format.

>> If you have suggestion on how to improve the new format, I'm sure we can
>> discuss that.  It seems pretty clear to me that we're not going back to
>> the old format.

>>I think there's no question that the new format is better in any case
>>where a function needs more than a couple words of documentation.
>>I could see the argument for adopting a more compact format for tables
>>that contain no such functions.  I think you might find that the set of
>>such tables is nigh empty, though; even section 9.3 (mathematical
>>functions) has a lot of functions that need a sentence or two.  We used
>>to either omit important details for such functions or stick them in
>>footnotes, and neither of those options is very nice.

>My observation is that the new format reduces one's ability to quickly skim the table to find out what is present since there is considerable extra information in one's eyes during that process that needs to be skimmed over.


I'm slow to the party, but I'm going to go with the new format is horrible. I agree with David that you can't quickly scan down the new table to find things like the return type (for example) which is something I do frequently. Go to the string funcs/ops page in v13, and try to quickly find the ones that return an "int" (because your goal is to find the position of something in a string so you know the return value will have to be an "int"). The new version makes that hard while the old version is easy. In fact, I couldn't even find the return type at first when I looked because there is no label (the power of tables with headers was removed).

The description and example also run together under the new format, which sort of comes across as a "wall of text". If I really zoom in, I can see they're different fonts, but at my normal zoom level they look pretty much the same at first glance.

This makes me want to stay on v12.x for as long as possible -- really.

If the maintainers are dead-set on maintaining the new format despite it drawbacks (and after reading all the other comments about the positives I'm going to say I don't see any positives**), then it'd be extremely helpful to do some CSS magic to make them easier to read. Personally, I'd like to see there be a setting for if media is HTML that it show the old table format, but if not, here's some ideas to make the new format more palatable:

* The return type needs to stand out a LOT more, bold would be a great start, adding color would help too.

* Make the description and example look much more different, again color or perhaps color banding (background a light gray or something on the example).

* Make the example code and example results more different, the simple "->" between them gets lost easily to my eye so it's harder to read as is.

* Can you add a few more classes to identify the parts betters in the tables? For example, I see the CSS class "returnvalue" on the example result, but there is nothing on the example code itself identifying it as such. If you did this better labeling then perhaps those of us who are complaining could attempt to overcome some of our objections by restyling the tables with colors & fonts & such. Not a full solution as that would require manipulating the DOM, but even small changes with color could bring large relief.

[** I think it was Bruce who pointed out the old table format was troublesome in the PDF format. I concede that and anything else for when you're constrained to paper. But I suspect most users look at these docs on a computer monitor with HTML so those size constraints aren't an issue there. Designing pages to the smallest media just frustrates those users on larger media (cue the many examples on the web where the left/right margins are so wide half of your screen is wasted instead of letting the text flow and resize).]

Kevin
This e-mail transmission, and any documents, files or previous e-mail messages attached to it, may contain confidential information. If you are not the intended recipient, or a person responsible for delivering it to the intended recipient, you are hereby notified that any disclosure, distribution, review, copy or use of any of the information contained in or attached to this message is STRICTLY PROHIBITED. If you have received this transmission in error, please immediately notify us by reply e-mail, and destroy the original transmission and its attachments without reading them or saving them to disk. Thank you.
Reply | Threaded
Open this post in threaded view
|

Re: New "function tables" in V13 documentation

David G Johnston
On Fri, Nov 13, 2020 at 12:20 PM Kevin Brannen <[hidden email]> wrote:
Go to the string funcs/ops page in v13, and try to quickly find the ones that return an "int" (because your goal is to find the position of something in a string so you know the return value will have to be an "int").

That is not something I considered...I figured people would look for a name that seems to reflect "position" or "in_string".  I've never felt the need to search based upon return type.
 
Designing pages to the smallest media just frustrates those users on larger media (cue the many examples on the web where the left/right margins are so wide half of your screen is wasted instead of letting the text flow and resize).]

It is just as bad it is so wide that one has to move their head instead of just moving their eyes.  If anything our tables could probably be improved by enforcing a maximum width to the content area.

David J.

12