Re: Optimizing the documentation

>
>
>
> > 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
>