From: Joshua D. Drake <jd@commandprompt.com>
To: Erik Rijkers <er@xs4all.nl>
To: Michael Paquier <michael@paquier.xyz>
Cc: Stephen Frost <sfrost@snowman.net>
Cc: pgsql-docs <pgsql-docs@postgresql.org>
Subject: Re: readability changes to postgres.sgml
Date: Tue, 20 Aug 2019 09:03:09 -0700
Message-ID: <259c0a83-b40f-7f19-4a91-d0be50168428@commandprompt.com> (raw)
In-Reply-To: <0b91a025a27aaade21809b7b7b72356a@xs4all.nl>
References: <5ac2c96d-37a6-18aa-08c4-327a6fbff24b@commandprompt.com>
<20190816002623.GS16436@tamriel.snowman.net>
<996bcfe233f558276f4f5962673ba164@xs4all.nl>
<bf0b706b7c4ab0f3f298b5d1c09f0b2c@xs4all.nl>
<317b2dec-264b-2085-fc9c-10f2feca3693@commandprompt.com>
<20190820050530.GC1841@paquier.xyz>
<0b91a025a27aaade21809b7b7b72356a@xs4all.nl>
On 8/19/19 10:36 PM, Erik Rijkers wrote:
> On 2019-08-20 07:05, Michael Paquier wrote:
>> On Mon, Aug 19, 2019 at 04:00:13PM -0700, Joshua D. Drake wrote:
>>> New version attached with spelling errors fixed.
>>
>> I have gone through this patch, and I have a hard time understanding
>> why these are improvements over the existing wording. In what does
>> this make things better?
>
> It's pretty simple, it improves readability. It does so mainly by
> removing unnecessary text.
>
> +1
>
Thanks for jumping in Erik. Michael, one of the cornerstones of good
writing is that you should only use exactly as many words as needed to
convey your point accurately. The more words, the more room for
interpretation, confusion and error from the readers side. It is easy
for us to look at the docs and say, "They are fine". We aren't reading
these docs as someone brand new to the project.
In short, the simpler we make our docs without sacrificing accuracy the
easier the docs will be to comprehend.
JD
--
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
Postgres centered full stack support, consulting and development.
Advocate: @amplifypostgres || Get help: https://commandprompt.com/
***** Unless otherwise stated, opinions are my own. *****
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: jd@commandprompt.com, er@xs4all.nl, michael@paquier.xyz, sfrost@snowman.net
Subject: Re: readability changes to postgres.sgml
In-Reply-To: <259c0a83-b40f-7f19-4a91-d0be50168428@commandprompt.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
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