Greetings, * Joshua D. Drake (j...@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
signature.asc
Description: PGP signature
