Re: Optimizing the documentation

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