On Mon, Dec 14, 2020 at 12:50 PM Joshua Drake <j...@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.
