Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1i06bP-0004Pg-UC for pgsql-docs@arkaria.postgresql.org; Tue, 20 Aug 2019 16:03:20 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1i06bO-0007QI-Kr for pgsql-docs@arkaria.postgresql.org; Tue, 20 Aug 2019 16:03:18 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1i06bO-0007Q9-Al for pgsql-docs@lists.postgresql.org; Tue, 20 Aug 2019 16:03:18 +0000 Received: from mail-pf1-x434.google.com ([2607:f8b0:4864:20::434]) by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1i06bK-00068C-Pu for pgsql-docs@postgresql.org; Tue, 20 Aug 2019 16:03:17 +0000 Received: by mail-pf1-x434.google.com with SMTP id o70so3654340pfg.5 for ; Tue, 20 Aug 2019 09:03:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=commandprompt-com.20150623.gappssmtp.com; s=20150623; h=subject:to:cc:references:from:organization:message-id:date :user-agent:mime-version:in-reply-to:content-transfer-encoding :content-language; bh=qLftwYxqgWKplCtDjRhqZ3bytRqFj7U2JrkGSbG8C4I=; b=FftbXIJ3AAV5LdPK2PKWTvfy2n2NBvULaJGlV/wbSSvIjc7oB7t7w0enu+Y3w9Apto DsebBpZVb8ysuN+aWZ05FqC+32USHZk7xM4C5/JQzxGF0/B8neClxuo1/7gvp/VzD3H5 KgH+UwIoHdhBTOrnX8oOsN8TFIzVumSYv3N1UHM0Fnal96ZSdIF8Vu6/gVQAFA4x38v7 uUtCO5GH8pGLX+tAkW9f09EizwUUmwnMZfhaTlyxvSHVD7xSOUns93vbmN3qFTINFZNO ifJbINo7wDuJvbPDs1JO7tXsxnFdUezza+ISZXZoAM87Snw8576LoegqwXij7EvLcaQt F1iA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:organization :message-id:date:user-agent:mime-version:in-reply-to :content-transfer-encoding:content-language; bh=qLftwYxqgWKplCtDjRhqZ3bytRqFj7U2JrkGSbG8C4I=; b=LCL9A07zy1tUYu+3ccysoVmnpsRiCV08DEKp5VfZkcMA63Glo1OqU3CZuXo725id1v bi/gaSKRAAoajCVOhldQfpmp2GACQf/QtkE4CTCTHM2g6QiHhEKVKO/6u49D06PrWX74 Yn+8XvaXvjvNYBG0Hp+FtAE+fU5vlabRO1jGcIsToiYmL2CYdy++9sli/yRvDv5UJatZ ungrNJUaNkqoiipXBUlppM/y7hy55TEnq6NjNYbSmUfY4Vf32Z4XGFRHIIKfUTJWo7rM azx44X/3ugTMNulhCWNK7CDq9grF2Cknry7vVordD9GBg6dL7DKx4VQD3QUpMghSjHp9 1sqQ== X-Gm-Message-State: APjAAAUUixKTcJUpswFtgAy6VjBHDR/pFIhUr6Cya9hVOBDQ5QWe86kM UBHg4mRW18yraLh39Ee/zPqLWYQMjsoUa9hWr5iIRFH1WXnhSlpIuTQTA3WZRbO5q9f0rtPpo3e 28WPK+yFwBzTclKg/DbtBsd5FRfP6f1Ug5Zv53UfHJlzd9YPKjxMIDEZBw27Bqs5YPLye/mM= X-Google-Smtp-Source: APXvYqxnYm4i5f5U1jY83jLJdQ2O4pOQvfubX11rVWoTln629EJSbZWyaAXHs2yC2LyN2r/ZZJeNRg== X-Received: by 2002:aa7:946d:: with SMTP id t13mr31546858pfq.121.1566316991480; Tue, 20 Aug 2019 09:03:11 -0700 (PDT) Received: from [192.168.50.160] (c-73-97-49-9.hsd1.wa.comcast.net. [73.97.49.9]) by smtp.gmail.com with ESMTPSA id d16sm11944883pfd.81.2019.08.20.09.03.10 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 20 Aug 2019 09:03:10 -0700 (PDT) Subject: Re: readability changes to postgres.sgml To: Erik Rijkers , Michael Paquier Cc: Stephen Frost , pgsql-docs References: <5ac2c96d-37a6-18aa-08c4-327a6fbff24b@commandprompt.com> <20190816002623.GS16436@tamriel.snowman.net> <996bcfe233f558276f4f5962673ba164@xs4all.nl> <317b2dec-264b-2085-fc9c-10f2feca3693@commandprompt.com> <20190820050530.GC1841@paquier.xyz> <0b91a025a27aaade21809b7b7b72356a@xs4all.nl> From: "Joshua D. Drake" Organization: Command Prompt, Inc. Message-ID: <259c0a83-b40f-7f19-4a91-d0be50168428@commandprompt.com> Date: Tue, 20 Aug 2019 09:03:09 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.8.0 MIME-Version: 1.0 In-Reply-To: <0b91a025a27aaade21809b7b7b72356a@xs4all.nl> Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Content-Language: en-US List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk 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. *****