Postgres Pro
Downloads
Home   >   mailing lists

Re: Optimizing the documentation - Mailing list pgsql-hackers

From David G. Johnston
Subject Re: Optimizing the documentation
Date
Msg-id CAKFQuwY0Pw0PJ11AHTkaGigptcPeNKwNf1PZ9ynUWAJS88AxXw@mail.gmail.com
Whole thread Raw
In response to Optimizing the documentation  (Joshua Drake <jd@commandprompt.com>)
Responses Re: Optimizing the documentation
List pgsql-hackers
Tree view
On Mon, Dec 14, 2020 at 12:50 PM Joshua Drake <jd@commandprompt.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.

pgsql-hackers by date:

Previous
From: Joshua Drake
Date:
Subject: Optimizing the documentation
Next
From: Heikki Linnakangas
Date:
Subject: Re: Optimizing the documentation