RE: New "function tables" in V13 documentation

[Kevin Brannen]

>From: Adrian Klaver 
>>On 11/15/20 9:00 AM, David G. Johnston wrote:
>
>> In hindsight it could have been handled better.  Waiting longer at
>> different points and making pronouncements on -announce to solicit
>> feedback from people who don't follow -docs.  That doesn't change the

> Yes and at least one post to --general. It would have motivated me to look at 
> the new docs earlier.

+1 on the post to -general.

FWIW... My attention to -announce is lazy but I'd see that eventually. I get a 
little behind on -general from time to time, but this is where I pay the most 
attention. I have no idea where most people are, perhaps the list maintainers 
could give some guidance on that.

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

Re: New "function tables" in V13 documentation

[Adrian Klaver]

On 11/15/20 9:00 AM, David G. Johnston wrote:
On Sun, Nov 15, 2020 at 9:39 AM Adrian Klaver > wrote:


On 11/14/20 8:24 PM, David G. Johnston wrote:
 > On Fri, Nov 13, 2020 at 1:48 PM Adrian Klaver
mailto:adrian.kla...@aklaver.com>
 > >> wrote:
 >
 >     Which is an indication that for changes of this scope it would be
 >     prudent to create a mock up and have end users see and comment on
 >     before
 >     rolling them out.
 >
 >
 > There were mockups and people did provide comments.  Do you have any

Where were they announced and when?


Starting back in February.

https://www.postgresql.org/message-id/9326.1581457...@sss.pgh.pa.us 



The first commit was applied in April.


 > concrete suggestions on what should have been done, or done
differently?

Yes my concrete suggestion was a return to previous layout.


I am referring to the process by which the idea to change the 
documentation layout was made public so people could review it (see above).


In hindsight it could have been handled better.  Waiting longer at 
different points and making pronouncements on -announce to solicit 
feedback from people who don't follow -docs.  That doesn't change the 


Yes and at least one post to --general. It would have motivated me to 
look at the new docs earlier.


fact that we need to move forward with a new patch to "fix" things.  If 
the agreement is that fix looks a lot like the old format then so be 
it.  But getting there by reverting doesn't seem doable.


The method does not matter to me the layout does.



David J.



--
Adrian Klaver
adrian.kla...@aklaver.com

Re: New "function tables" in V13 documentation

[Adrian Klaver]

On 11/14/20 8:24 PM, David G. Johnston wrote:
On Fri, Nov 13, 2020 at 1:48 PM Adrian Klaver > wrote:


Which is an indication that for changes of this scope it would be
prudent to create a mock up and have end users see and comment on
before
rolling them out.


There were mockups and people did provide comments.  Do you have any 


Just realized the mockups would have been in the devel version of the 
docs. I will have to admit to not looking at those as I don't usually 
follow that until they become the final release docs. My mistake and I 
will pay more attention in the future.



concrete suggestions on what should have been done, or done differently?

David J.



--
Adrian Klaver
adrian.kla...@aklaver.com

Re: New "function tables" in V13 documentation

[David G. Johnston]

On Sun, Nov 15, 2020 at 9:39 AM Adrian Klaver 
wrote:

> On 11/14/20 8:24 PM, David G. Johnston wrote:
> > On Fri, Nov 13, 2020 at 1:48 PM Adrian Klaver  > > wrote:
> >
> > Which is an indication that for changes of this scope it would be
> > prudent to create a mock up and have end users see and comment on
> > before
> > rolling them out.
> >
> >
> > There were mockups and people did provide comments.  Do you have any
>
> Where were they announced and when?
>

Starting back in February.

https://www.postgresql.org/message-id/9326.1581457...@sss.pgh.pa.us

The first commit was applied in April.

>
> > concrete suggestions on what should have been done, or done differently?
>
> Yes my concrete suggestion was a return to previous layout.
>

I am referring to the process by which the idea to change the documentation
layout was made public so people could review it (see above).

In hindsight it could have been handled better.  Waiting longer at
different points and making pronouncements on -announce to solicit feedback
from people who don't follow -docs.  That doesn't change the fact that we
need to move forward with a new patch to "fix" things.  If the agreement is
that fix looks a lot like the old format then so be it.  But getting there
by reverting doesn't seem doable.

David J.

Re: New "function tables" in V13 documentation

[Adrian Klaver]

On 11/14/20 8:24 PM, David G. Johnston wrote:
On Fri, Nov 13, 2020 at 1:48 PM Adrian Klaver > wrote:


Which is an indication that for changes of this scope it would be
prudent to create a mock up and have end users see and comment on
before
rolling them out.


There were mockups and people did provide comments.  Do you have any 


Where were they announced and when?


concrete suggestions on what should have been done, or done differently?


Yes my concrete suggestion was a return to previous layout. It was 
rejected out of hand. I still think that the previous layout is a 
significant improvement over the current layout. Namely, you could see 
more and pick out the information quicker. The current setup is as Kevin 
said an amorphous 'wall of text'. Losing the columns was a big mistake, 
they should be returned.




David J.



--
Adrian Klaver
adrian.kla...@aklaver.com

Re: New "function tables" in V13 documentation

[David G. Johnston]

On Fri, Nov 13, 2020 at 1:48 PM Adrian Klaver 
wrote:

> Which is an indication that for changes of this scope it would be
> prudent to create a mock up and have end users see and comment on before
> rolling them out.
>

There were mockups and people did provide comments.  Do you have any
concrete suggestions on what should have been done, or done differently?

David J.

RE: New "function tables" in V13 documentation

[Kevin Brannen]

>From: David G. Johnston 



>>On Fri, Nov 13, 2020 at 12:20 PM Kevin Brannen  
>>wrote:

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





True on moving heads is harder, but we have the option of making the browser 
narrower to compensate

if we feel the need.  When there are max width constraints then the option to 
customize is taken out

of the user's hands and that's an issue. Let the user do what works best for 
them. Some flexibility

doesn't seem like to much to ask for...IMO.



I really don't expect the old tables to come back, as much as I'd like that, 
because groups rarely backtrack

or so my experience has been. However, this is also why I made the suggestions 
I did, especially the

last one about adding more CSS classes to let the users restyle if they feel 
strongly enough about it.



Maybe this works for most people:



upper ( text ) → text

Converts the string to all upper case, according to the rules of the 
database's locale.

  upper('tom') → TOM



By why not let people do:



upper ( text ) → text

Converts the string to all upper case, according to the rules of the 
database's locale.

  upper('tom') → TOM



[For those that don’t receive HTML in email, the function is bold, the return 
type is underlined,

the example has a light gray background, and the example result has a light 
blue background.]



I don’t know that I’d really do it that way, but the CSS required for that 
isn’t hard yet it makes

the parts stand out a lot better so I know what is what. The current docs are 
only missing 3 CSS

classes to allow me to do that: the description, the example code, and the 
example return (since it

uses the same class as the function return value). I can’t imagine that would 
be so hard to do.



I don’t see myself contributing to the Pg code base, but this is something I 
might could do and

should look into.



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.

Re: New "function tables" in V13 documentation

[Adrian Klaver]

On 11/13/20 11:30 AM, David G. Johnston wrote:
On Fri, Nov 13, 2020 at 12:20 PM Kevin Brannen > 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.


Which is an indication that for changes of this scope it would be 
prudent to create a mock up and have end users see and comment on before 
rolling them out.




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.




--
Adrian Klaver
adrian.kla...@aklaver.com

Re: New "function tables" in V13 documentation

[Adrian Klaver]

On 11/13/20 11:20 AM, Kevin Brannen wrote:

From: David G. Johnston 



On Mon, Nov 9, 2020 at 1:41 PM Tom Lane  wrote:
Alvaro Herrera  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.


+1



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


Second the motion.



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.




--
Adrian 

Re: New "function tables" in V13 documentation

[David G. Johnston]

On Fri, Nov 13, 2020 at 12:20 PM Kevin Brannen  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.

RE: New "function tables" in V13 documentation

[Kevin Brannen]

>From: David G. Johnston 

>On Mon, Nov 9, 2020 at 1:41 PM Tom Lane  wrote:
>Alvaro Herrera  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.

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  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  https://momjian.us
  EnterpriseDB https://enterprisedb.com

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

Re: New "function tables" in V13 documentation

[Merlin Moncure]

On Sun, Nov 8, 2020 at 3: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/

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

Re: New "function tables" in V13 documentation

[David G. Johnston]

On Mon, Nov 9, 2020 at 3:30 PM Ron  wrote:

> On 11/9/20 3:05 PM, David G. Johnston wrote:
>
> On Mon, Nov 9, 2020 at 2:01 PM Ron  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.

Re: New "function tables" in V13 documentation

[Ron]

On 11/9/20 3:05 PM, David G. Johnston wrote:
On Mon, Nov 9, 2020 at 2:01 PM Ron > 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.

Re: New "function tables" in V13 documentation

[David G. Johnston]

On Mon, Nov 9, 2020 at 2:01 PM Ron  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.

Re: New "function tables" in V13 documentation

[Ron]

On 11/9/20 2:47 PM, David G. Johnston wrote:
On Mon, Nov 9, 2020 at 1:41 PM Tom Lane > wrote:


Alvaro Herrera mailto:alvhe...@alvh.no-ip.org>> 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.

Re: New "function tables" in V13 documentation

[Tom Lane]

=?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?=  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

Re: New "function tables" in V13 documentation

[Adrian Klaver]

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
adrian.kla...@aklaver.com

Re: New "function tables" in V13 documentation

[David G. Johnston]

On Mon, Nov 9, 2020 at 1:41 PM Tom Lane  wrote:

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

Re: New "function tables" in V13 documentation

[Tom Lane]

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

Re: New "function tables" in V13 documentation

[Josef Šimánek]

po 9. 11. 2020 v 21:35 odesílatel Alvaro Herrera
 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?

>
>

Re: New "function tables" in V13 documentation

[David G. Johnston]

On Mon, Nov 9, 2020 at 1:33 PM Adrian Klaver 
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.

Re: New "function tables" in V13 documentation

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

Re: New "function tables" in V13 documentation

[Adrian Klaver]

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
adrian.kla...@aklaver.com

Re: New "function tables" in V13 documentation

[Alvaro Herrera]

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.

Re: New "function tables" in V13 documentation

[Tony Shelver]

On Mon, 9 Nov 2020 at 02:54, 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.
>
> >
> >
> > Thomas
> >
> >
>
>
> --
> Adrian Klaver
> adrian.kla...@aklaver.com
>
> Agreed, old format much more readable.
>

Re: New "function tables" in V13 documentation

[Adrian Klaver]

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
adrian.kla...@aklaver.com