Re: Optimizing the documentation - Mailing list pgsql-hackers

On 14/12/2020 21:50, Joshua Drake wrote:
> The community has spent a lot of time optimizing features over the 
> years. Excellent examples include parallel query and partitioning which 
> have been multi-year efforts to increase the quality,  performance, and 
> extend features of the original commit. We should consider the 
> documentation in a similar manner. Just like code, documentation can 
> sometimes use a bug fix, optimization, and/or new features added to the 
> original implementation.
> 
> Technical documentation should only be as verbose as needed to 
> illustrate the concept or task that we are explaining. It should not be 
> redundant, nor should it use .50 cent words when a .10 cent word would 
> suffice. I would like to put effort into optimizing the documentation 
> and am requesting general consensus that this would be a worthwhile 
> effort before I begin to dust off my Docbook skills.

Hard to argue with "let's make the doc better" :-).

I expect that there will be a lot of bikeshedding over the exact 
phrases. That's OK. Every improvement that actually gets committed 
helps, even if we don't make progress on other parts.

> I have provided an example below:
> 
> 
> Original text (79 words):
> 
> 
> 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.
> 
> To make the large amount of information about PostgreSQL manageable, 
> 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:
> 
> Optimized text (35 words):
> 
> 
> 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.

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

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

> Issues that are resolved with the optimized text:
> 
>   * Succinct text is more likely to be read than skimmed
> 
>   * Removal of extraneous mentions of PostgreSQL
> 
>   * Removal of unneeded justifications
> 
>   * Joining of two paragraphs into one that provides only the needed
>     information to the user
> 
>   * Word count decreased by over 50%. As changes such as these are
>     adopted it would make the documentation more consumable.
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.

- Heikki