Re: Optimizing the documentation

>
>
>>
>> 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 considered just starting to review patches as such but even with that,
doesn't it make sense that if I am going to be putting a particular thought
process into my efforts that there is a general consensus? For example,
what would be exceedly helpful would be a documentation style guide that is
canonical and we can review documentation against. Currently our
documentation is all over the place. It isn't that it is not technically
accurate or comprehensive

> 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?
>

Yes. https://www.postgresql.org/docs/13/preface.html

> 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.
>

It is a matter of consistency.

>
> 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.
>

One of the issues is that editing documentation with patches is a pain. It
is simpler and a lower barrier of effort to pull up an existing section of
Docbook and edit that (just like code) than it is to break out specific
text within a patch. Though I would be happy to take a swipe at reviewing a
specific documentation patch (as you linked).

>
> 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.
>

I wasn't planning on reading random chapters. I was planning on walking
through the documentation as it is written and hopefully others would join.
This is a monumental effort to perform completely. Also consider the
overall benefit, not just one specific piece. Would you not consider it a
net win if certain questions were being answered in a succinct way as to
allow users to use the documentation instead of asking the most novice of
questions on various channels?

JD

>
>