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