Re: Optimizing the documentation - Mailing list pgsql-hackers

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/

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.