Thread: readability changes to postgres.sgml
attached Thanks, 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. *****
Attachment
Greetings, * Joshua D. Drake (jd@commandprompt.com) wrote: > attached While I'm all for working on improving the documentation and, in particular, our tutorials, the above description of what the suggested change is seems to be rather.. lacking, and the changes themselves don't come across as obvious or clear improvements (and in some cases they seem to be simply removing words and removing content that is actually important and valuable, making it a net negative change). Specifically- > Welcome to the <productname>PostgreSQL</productname> Tutorial. The > - following few chapters are intended to give a simple introduction > + tutorial is intended to give an introduction > to <productname>PostgreSQL</productname>, relational database I disagree with removing 'simple'- after all, that's exactly what we want this tutorial to be and including that hopefully encourages individuals to move forward. I'd argue the same applies to pointing out that the tutorial itself is only a few chapters and isn't the whole rest of the documentation. > - concepts, and the SQL language to those who are new to any one of > - these aspects. We only assume some general knowledge about how to > - use computers. No particular Unix or programming experience is > - required. This part is mainly intended to give you some hands-on > - experience with important aspects of the > - <productname>PostgreSQL</productname> system. It makes no attempt > - to be a complete or thorough treatment of the topics it covers. > + concepts, and the SQL language. We assume some general knowledge about > + how to use computers and no particular Unix or programming experience is > + required. This tutorial is intended to provide hands-on experience with > + important aspects of the <productname>PostgreSQL</productname> system. > + It makes no attempt to be a comprehensive treatment of the topics it covers. > </para> This seems to primairly just remove the "who are new to any one of those aspects" but that's pretty key to the goal of this tutorial and it speaks to how we should be thinking about the rest of this part of the documentation. > <para> > - After you have worked through this tutorial you might want to move > - on to reading <xref linkend="sql"/> to gain a more formal knowledge > + After you have successfully completed this tutorial you will want to > + read the <xref linkend="sql"/> section to gain a better understanding > of the SQL language, or <xref linkend="client-interfaces"/> for > - information about developing applications for > - <productname>PostgreSQL</productname>. Those who set up and > - manage their own server should also read <xref linkend="admin"/>. > + information about developing applications with > + <productname>PostgreSQL</productname>. Those who provision and > + manage their own PostgreSQL installation should also read <xref linkend="admin"/>. > </para> > </partintro> Why change "might" to "will"..? Or remove "formal"? Also not sure about changing "set up" to "provision", the latter seems to imply a particular environment while the former doesn't. > @@ -66,28 +64,26 @@ > This part describes the use of the <acronym>SQL</acronym> language > in <productname>PostgreSQL</productname>. We start with > describing the general syntax of <acronym>SQL</acronym>, then > - explain how to create the structures to hold data, how to populate > - the database, and how to query it. The middle part lists the > - available data types and functions for use in > - <acronym>SQL</acronym> commands. The rest treats several > - aspects that are important for tuning a database for optimal > - performance. > + how to create tables, how to populate the database, and how to > + query it. The middle part lists the available data types and > + functions for use in <acronym>SQL</acronym> commands. Lasty, > + we address several aspects of importantance for tuning a database. > </para> The term "structures to hold data" seems to be specifically used because we haven't yet defined what a 'table' is, so I don't agree with this change either. The later changes seem to be in a similar vein.. Dropping things like "language" when talking about server-side programming languages, removing references to "in this part" or changing them to be "in this tutorial" or similar, and just don't strike me as particularly good improvements or ones which have a specific direction or a defined reason for being made. Thanks, Stephen
Attachment
On 2019-08-16 02:26, Stephen Frost wrote: > Greetings, > > * Joshua D. Drake (jd@commandprompt.com) wrote: >> attached > they seem to be simply removing words and removing content that is For what it's worth, I think the proposed changes are all solid improvements. The text reads better with them, and that's what this is about -- not whether the removed little text-pieces were 'true' or not. However, there is one typo: + read independently. There are many extrernal programming extrernal -> external (and I would say that dropping that word 'external' would be another little improvement)
For what it's worth, I think the proposed changes are all solid
improvements. The text reads better with them, and that's what this is
about -- not whether the removed little text-pieces were 'true' or not.
I'm afraid I can't agree that all changes are good enough (e.g. "start with describing the general syntax of <acronym>SQL</acronym>, then how to create tables.." used to be better with a verb, and "Readers are encouraged review" is probably too liberal grammar). Changes like "encouraged to look" vs. the original "should see" can be also challenged as an improvement - IMHO the original version reads equally well (although it could be more concise for sure).
That said, I agree we should not hold on to every word just because it was written - the shorter the docs, the more chances they get to be actually read. Avoiding assumptions about what's simple may also be beneficial. A simple concept for one can be new and unclear to another, no matter how experienced they actually are.
That said, I agree we should not hold on to every word just because it was written - the shorter the docs, the more chances they get to be actually read. Avoiding assumptions about what's simple may also be beneficial. A simple concept for one can be new and unclear to another, no matter how experienced they actually are.
If we want to make these intros more concise, one of the easiest ways to achieve this is to address the reader directly ("Readers looking for xxx are encouraged to look" vs. smth like "For xxx, see"). We can also question the need for some of the provided info - for example, assumptions about typical user behavior and complexity of the text that follows could probably be let gone altogether. I don't believe they can actually guide anyone as they are quite vague anyway (how many are "the first few" chapters exactly?) That would leave us with the scope of the chapters described and explicit references to elsewhere (if required for clarity), making the most valuable parts here more prominent and not-so-easy to skip.
Best regards,
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
On 2019-08-16 07:22, Erik Rijkers wrote: > On 2019-08-16 02:26, Stephen Frost wrote: >> Greetings, >> >> * Joshua D. Drake (jd@commandprompt.com) wrote: >>> attached > >> they seem to be simply removing words and removing content that is > > For what it's worth, I think the proposed changes are all solid > improvements. The text reads better with them, and that's what this is > about -- not whether the removed little text-pieces were 'true' or > not. > > > However, there is one typo: > > + read independently. There are many extrernal programming > > extrernal -> external > (and I would say that dropping that word 'external' would be another > little improvement) and: Lasty -> Lastly importantance -> importance
On 8/15/19 10:22 PM, Erik Rijkers wrote: > On 2019-08-16 02:26, Stephen Frost wrote: >> Greetings, >> >> * Joshua D. Drake (jd@commandprompt.com) wrote: >>> attached > >> they seem to be simply removing words and removing content that is > > For what it's worth, I think the proposed changes are all solid > improvements. The text reads better with them, and that's what this is > about -- not whether the removed little text-pieces were 'true' or not. Correct, the point of these patches is to make the documentation succinct and hopefully more clear. Any writing class you take will tell you that the less words you can use to make the point, the better. Further, language interpretation changes over time and certain adjectives will not have the impact they once did. As I have been reviewing the docs, the language used although correct is often clumsy. > > However, there is one typo: > > + read independently. There are many extrernal programming > > extrernal -> external > (and I would say that dropping that word 'external' would be another > little improvement) > Good catch, should I submit a new patch or will it be fixed if applied? 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. *****
On 8/16/19 10:41 AM, Liudmila Mantrova wrote:
>
>
> For what it's worth, I think the proposed changes are all solid
> improvements. The text reads better with them, and that's what
> this is
> about -- not whether the removed little text-pieces were 'true' or
> not.
>
> If we want to make these intros more concise, one of the easiest ways
> to achieve this is to address the reader directly ("Readers looking
> for xxx are encouraged to look" vs. smth like "For xxx, see").
This is true and my counter argument is that a call to action is more
likely to get the reader to do something.
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. *****
On 8/15/19 5:26 PM, Stephen Frost wrote: > > Specifically- > >> Welcome to the <productname>PostgreSQL</productname> Tutorial. The >> - following few chapters are intended to give a simple introduction >> + tutorial is intended to give an introduction >> to <productname>PostgreSQL</productname>, relational database > I disagree with removing 'simple'- after all, that's exactly what we > want this tutorial to be and including that hopefully encourages > individuals to move forward. I'd argue the same applies to pointing out > that the tutorial itself is only a few chapters and isn't the whole rest > of the documentation. I would argue the use of the word introduction implicitly suggests the unneeded word, "simple". >> - concepts, and the SQL language to those who are new to any one of >> - these aspects. We only assume some general knowledge about how to >> - use computers. No particular Unix or programming experience is >> - required. This part is mainly intended to give you some hands-on >> - experience with important aspects of the >> - <productname>PostgreSQL</productname> system. It makes no attempt >> - to be a complete or thorough treatment of the topics it covers. >> + concepts, and the SQL language. We assume some general knowledge about >> + how to use computers and no particular Unix or programming experience is >> + required. This tutorial is intended to provide hands-on experience with >> + important aspects of the <productname>PostgreSQL</productname> system. >> + It makes no attempt to be a comprehensive treatment of the topics it covers. >> </para> > This seems to primairly just remove the "who are new to any one of those > aspects" but that's pretty key to the goal of this tutorial and it > speaks to how we should be thinking about the rest of this part of the > documentation. I do not believe that is true. We clearly state, "It makes no attempt to be a complete or thorough treatment of the topics it covers. concepts, and the SQL language". Adding "who are new to any one of those aspects" is redundant when read in context of the content. > >> <para> >> - After you have worked through this tutorial you might want to move >> - on to reading <xref linkend="sql"/> to gain a more formal knowledge >> + After you have successfully completed this tutorial you will want to >> + read the <xref linkend="sql"/> section to gain a better understanding >> of the SQL language, or <xref linkend="client-interfaces"/> for >> - information about developing applications for >> - <productname>PostgreSQL</productname>. Those who set up and >> - manage their own server should also read <xref linkend="admin"/>. >> + information about developing applications with >> + <productname>PostgreSQL</productname>. Those who provision and >> + manage their own PostgreSQL installation should also read <xref linkend="admin"/>. >> </para> >> </partintro> > Why change "might" to "will"..? Or remove "formal"? Also not sure > about changing "set up" to "provision", the latter seems to imply a > particular environment while the former doesn't. A call to action should be formal. Using "might" concludes that they may not need more information. We want to definitely encourage people to read more documentation. The use of the word formal is just not needed. We already state they will gain more knowledge, why do we need the word formal at all? > >> @@ -66,28 +64,26 @@ >> This part describes the use of the <acronym>SQL</acronym> language >> in <productname>PostgreSQL</productname>. We start with >> describing the general syntax of <acronym>SQL</acronym>, then >> - explain how to create the structures to hold data, how to populate >> - the database, and how to query it. The middle part lists the >> - available data types and functions for use in >> - <acronym>SQL</acronym> commands. The rest treats several >> - aspects that are important for tuning a database for optimal >> - performance. >> + how to create tables, how to populate the database, and how to >> + query it. The middle part lists the available data types and >> + functions for use in <acronym>SQL</acronym> commands. Lasty, >> + we address several aspects of importantance for tuning a database. >> </para> > The term "structures to hold data" seems to be specifically used because > we haven't yet defined what a 'table' is, so I don't agree with this > change either. Interesting, there may be a point here but I would say that it is likely the user knows what a table is and if not, they can "insert search engine or dictionary here). I could see an argument for "data table" or "database table". I removed "structures to hold data" because it says literally nothing. What structure? Is this a barrel, a building, a car? If we keep that sentence then I believe we should define it right there, it should be "structures to hold data (table)" or something. > The later changes seem to be in a similar vein.. Dropping things like > "language" when talking about server-side programming languages, > removing references to "in this part" or changing them to be "in this > tutorial" or similar, and just don't strike me as particularly good > improvements or ones which have a specific direction or a defined reason > for being made. As others have mentioned, it improves readability. We should be using exactly the amount of words needed to describe "whatever", no more, no less. The more words, the more there is open for interpretation and confusion. JD > Thanks, > > Stephen -- 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. *****
Team, New version attached with spelling errors fixed. -- 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. *****
Attachment
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? -- Michael
Attachment
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
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. *****
On Mon, Aug 19, 2019 at 04:00:13PM -0700, Joshua D. Drake wrote: > Team, > > New version attached with spelling errors fixed. After four years, patch applied to master. I know reviews had trouble reviewing this, and I found git diff --word-diff=color to be very helpful for this patch. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com Only you can decide what is important to you.
Blink... thanks!
and also for the tips.
On Wed, Nov 8, 2023 at 1:48 PM Bruce Momjian <bruce@momjian.us> wrote:
On Mon, Aug 19, 2019 at 04:00:13PM -0700, Joshua D. Drake wrote:
> Team,
>
> New version attached with spelling errors fixed.
After four years, patch applied to master. I know reviews had trouble
reviewing this, and I found git diff --word-diff=color to be very
helpful for this patch.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.