Re: postgres documentation - proposed improvement/clarification

>>=20
>>         permitted values (in kB): -1 (auto-tuning)  and 32-65536.
> =3D=3D=3D> what does '32-65536' mean?  I know what it means, but if someo=
ne is very stressed and looking at it for the first time, it looks like non=
sense!

Indeed, this is an interesting special case that I used to draw out this pr=
oblem.
The documentation mentions that values below 32 are treated as 32.=20
But I don't think we should try to squeeze the entire documentation into th=
at line.=20

In this particular example though, saying 0-65536 might be considered misle=
ading since some of those values change into 32.
32-65536 is confusing in a slightly different sense, because 0-31 are actua=
lly valid possibilities, but they definitely don't do what you'd expect.

The underlying issue is:

a) should you list the complete range of inputs that postgresql will accept=
 as a permitted value?
b) or should you list the complete range of 'sensible' inputs that postgres=
ql will accept as a permitted value?=20

Perhaps you are right and (a) is an easier choice to maintain. =20

Graeme.




On 02 Jun 2015, at 21:19, Gavin Flower <GavinFlower@archidevsys.co.nz> wrot=
e:

> On 02/06/15 23:58, Graeme B. Bell wrote:
>> Hi everyone
>>=20
>> The documentation for postgres is generally great, but I noticed a probl=
em today while using the doc webpages to reply to a user on the pgsql-perfo=
rmance mailing list.
>>=20
>> The problem relates to how default settings are communicated in the docu=
mentation. Keep in mind that not all postgresql admins have English as thei=
r first language, so it should not be necessary to guess from the phrasing =
of a paragraph about what is set by default. Also, many people keep around =
older config files, or don't have a vanilla postgresql.conf file handy to c=
heck for reference (and you never know, someone might have modified your va=
nilla reference .conf...). So the documentation is for many the primary ref=
erence and it should be clear exactly what postgres does in the absence of =
actively chosen configuration settings. It should also be clear what those =
settings can be, and how they should be entered.
>>=20
>> Take a look at this page, as an example:   http://www.postgresql.org/doc=
s/9.4/static/runtime-config-wal.html
>>=20
>> Thoughts:
>>=20
>> 1. Default values are not always specified for each setting, but should =
be.
>> Example: documentation for fsync (boolean) doesn't have the default spec=
ified.
>>=20
>>=20
>> 2. Default values are not specified in a consistent place or style in th=
e text.
>> Examples: take a look at
>> wal_level (enum)
>> full_page_writes (boolean)
>> wal_buffers (integer)
>>=20
>>=20
>> 3. Information about default values are sometimes mixed into longer sent=
ences on another topic. This isn't a big problem but it makes it harder to =
spot the default value in the paragraph.
>> Example:
>> wal_buffers (integer)
>>=20
>>=20
>> 4. Default values are sometimes documented in a slightly different style=
 or format to their actual use in the config file. For example, integers li=
ke 5 are given as text 'five'. This isn't a big problem but it makes it har=
der to find the default value in the paragraph; you're looking for an integ=
er in the text, but the number is written as a string. It might be better t=
o break the writing convention of putting some numbers as text in English. =
This is a document explaining what to type into the config file. Examples o=
r defaults should always be valid cases if  copied directly into the config=
 file.
>>=20
>> Example:
>> commit_delay (integer)
>> "The default commit_delay is zero (no delay)"        (actual commit_dela=
y default is '0', of course, not 'zero')
>> vs.
>> checkpoint_completion_target (floating point)
>> "The default is 0.5."
>>=20
>>=20
>> 5. Where the type is specified as 'boolean', the normal & default values=
 are not 'true/false' or '1/0', as would be expected for a boolean typed pa=
rameter. Yes, I know on/off is also boolean, but I bet if you surveyed 100 =
programmers and asked them about likely default values for a boolean settin=
g, few would say 'on' in reply. It actually makes me wonder if this is bett=
er described to users as a 2-value enum type.
>> Example:
>> full_page_writes (boolean)
>> "The default is on."
>>=20
>>=20
>> 6. The present method of documenting the datatype alongside the name isn=
't actually that helpful for most people reading the documentation. How man=
y readers are helped by knowing that wal_sync_method is an (enum) as the fi=
rst thing they read about it?
>>=20
>>=20
>> 7. Default units? And should units be included in the setting value?
>>=20
>> Look at this example. Can anyone tell me, using *only* reference to this=
 parameter documentation, if the parameter can be set to "8", "8kB", "8KB" =
or "8MB" in the config file?
>> Again, using only this documentation, can you tell for certain that if I=
 choose '8' it will be bytes , or kb, or a configuration error?
>>=20
>> =3D=3D=3D=3D=3D
>> wal_buffers (integer)
>> The amount of shared memory used for WAL data that has not yet been writ=
ten to disk. The default setting of -1 selects a size equal to 1/32nd (abou=
t 3%) ofshared_buffers, but not less than 64kB nor more than the size of on=
e WAL segment, typically 16MB. This value can be set manually if the automa=
tic choice is too large or too small, but any positive value less than 32kB=
 will be treated as 32kB. This parameter can only be set at server start.
>>=20
>> The contents of the WAL buffers are written out to disk at every transac=
tion commit, so extremely large values are unlikely to provide a significan=
t benefit. However, setting this value to at least a few megabytes can impr=
ove write performance on a busy server where many clients are committing at=
 once. The auto-tuning selected by the default setting of -1 should give re=
asonable results in most cases.
>> =3D=3D=3D=3D=3D
>>=20
>>=20
>>=20
>> Proposed solutions.
>>=20
>> Perhaps it might be worth extending or replacing the type information in=
 the header, by including info about the default, possibly replacing the ty=
pe info at that part of the document.
>>=20
>>=20
>> e.g. How about this style?
>>=20
>>         synchronous_commit (default: on)
>>=20
>>         Specifies whether transaction commit will wait for WAL records to be..=
.
>>=20
>>=20
>> or this style?
>>=20
>>         synchronous_commit (enum, default: on)
>>=20
>>         Specifies whether transaction commit will wait for WAL records to be..=
.
>>=20
>>=20
>> or this?
>>=20
>>         synchronous_commit (enum)
>>         permitted values: on, remote_write, local, off
>>         default: on
>>     =09
>>=20
>>         wal_buffers (integer)
>>         permitted values (in kB): -1 (auto-tuning)  and 32-65536.
> =3D=3D=3D> what does '32-65536' mean?  I know what it means, but if someo=
ne is very stressed and looking at it for the first time, it looks like non=
sense!
>>         default: -1
>>=20
>>=20
>>=20
>>=20
>> In most cases, this information is there in the paragraph somewhere, but=
 presenting the config option in this way would make it easier to refer to =
without needing to parse and understand the entire description to understan=
d the default and permitted settings.
>>=20
>> This would make it easier for people to quickly check how their server i=
s setup if a) the config file is lacking the setting or b) may have been mo=
dified in the past or c) may have been retained from a previous version of =
postgres with different defaults.
>>=20
>> It also means that we don't need e.g. duplicate specification of default=
 values in the text description - e.g. take a look at wal_buffers (integer)=
, which specifies it twice.
>>=20
>> Thoughts?
>>=20
>> Graeme Bell
>>=20
>>=20
>>=20
>>=20
>>=20
>>=20
> I suggest that boolean values should use either true or false, consistent=
ly..
>=20
>=20
> Cheers,
> Gavin
>=20
>=20
>=20
> --=20
> Sent via pgsql-bugs mailing list (pgsql-bugs@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-bugs