Re: Optimizing the documentation - Mailing list pgsql-hackers

From Joshua Drake
Subject Re: Optimizing the documentation
Date
Msg-id CAJvJg-SVGfGhN_ssV-BmpnOuosaT40s5s6p256L=S4ve0+yHUw@mail.gmail.com
Whole thread Raw
In response to Re: Optimizing the documentation  (Heikki Linnakangas <hlinnaka@iki.fi>)
List pgsql-hackers


> 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

pgsql-hackers by date:

Previous
From: Joshua Drake
Date:
Subject: Re: Optimizing the documentation
Next
From: Tom Lane
Date:
Subject: Re: Optimizing the documentation