Re: Optimizing the documentation - Mailing list pgsql-hackers

From Joshua Drake
Subject Re: Optimizing the documentation
Date
Msg-id CAJvJg-ThTQ+SVN0kJLohh15ZsfE3Hi5BUXAv_Wa5eVLMdQR00w@mail.gmail.com
Whole thread Raw
In response to Re: Optimizing the documentation  ("David G. Johnston" <david.g.johnston@gmail.com>)
Responses Re: Optimizing the documentation
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.


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? 

 
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

pgsql-hackers by date:

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