> > > > > This is the official PostgreSQL documentation. It is written by the > > PostgreSQL community in parallel with the development of the software. > > We have organized it by the type of user and their stages of experience: > > Some thoughts on this example: > > - Changing "has been" to "is" changes the tone here. "Is" implies that > it is being written continuously, whereas "has been" implies that it's > finished. We do update the docs continuously, but point of the sentence > is that the docs were developed together with the features, so "has > been" seems more accurate. >
No argument. > > ยด- I like "PostgreSQL developers and other volunteers" better than the > "PostgreSQL community". This is the very first introduction to > PostgreSQL, so we can't expect the reader to know what the "PostgreSQL > community" is. I like the "volunteers" word here a lot. > > There is a huge community for PostgreSQL, the developers are only a small (albeit critical) part of it. By using the term "PostgreSQL community" we are providing equity to all those who participate in the success of the project. I could definitely see saying "PostgreSQL volunteers". > - I think a little bit of ceremony is actually OK in this particular > paragraph, since it's the very first one in the docs. > > - I agree with dropping the "to make the large amount of information > manageable". > > So I would largely keep this example unchanged, changing it into: > > --- > This book is the official documentation of PostgreSQL. It has been > written by the PostgreSQL developers and other volunteers in parallel to > the development of the PostgreSQL software. It describes all the > functionality that the current version of PostgreSQL officially supports. > > This book has been organized in several parts. Each part is targeted at > a different class of users, or at users in different stages of their > PostgreSQL experience: > --- > > I appreciate the feedback and before we get too far down the rabbit hole, I would like to note that I am not tied to an exact wording as my post was more about the general goal and results based on that goal. > I agree with these goals in general. I like to refer to > http://www.plainenglish.co.uk/how-to-write-in-plain-english.html when > writing documentation. Or anything else, really. > Great resource! JD > > - Heikki >
