Re: readability changes to postgres.sgml
"Joshua D. Drake" <[email protected]>
| Newsgroups | gmane.comp.db.postgresql.devel.documentation |
|---|---|
| Organization | Command Prompt, Inc. |
| Message-ID | <[email protected]> |
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. *****