Re: Optimizing the documentation

On Mon, Dec 14, 2020 at 12:50 PM Joshua Drake <jd(at)commandprompt(dot)com> wrote:

> -hackers,
>
> 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.
>
>
As a quick observation, it would be more immediately helpful to add to the
existing proposal to add more details about architecture and get that
committed before embarking on a new documentation project.

https://commitfest.postgresql.org/31/2541/

> 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:
>
> 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.
>
> That actually exists in our documentation? I suspect changing it isn't
all that worthwhile as the typical user isn't reading the documentation
like a book and with the entry point being the table of contents most of
that material is simply gleaned from observing the presented structure
without words needed to describe it.

While I don't think making readability changes is a bad thing, and maybe my
perspective is a bit biased and negative right now, but the attention given
to the existing documentation patches in the commitfest isn't that great -
so adding another mass of patches fixing up items that haven't provoked
complaints seems likely to just make the list longer.

In short, I don't think optimization should be a goal in its own right; but
rather changes should mostly be driven by questions asked by our users. I
don't think reading random chapters of the documentation to find
non-optimal exposition is going to be a good use of time.

David J.