Re: Optimizing the documentation - Mailing list pgsql-hackers
| From | David G. Johnston |
|---|---|
| Subject | Re: Optimizing the documentation |
| Date | |
| Msg-id | CAKFQuwZ+-V9695xRs9ZKUatYTcCY1zO26pCbb4N0VVTwt8LjUA@mail.gmail.com Whole thread Raw |
| In response to | Re: Optimizing the documentation (Joshua Drake <jd@commandprompt.com>) |
| List | pgsql-hackers |
On Mon, Dec 14, 2020 at 1:40 PM Joshua Drake <jd@commandprompt.com> wrote:
For example, what would be exceedly helpful would be a documentation style guide that is canonical and we can review documentation against.
I do agree with that premise, with the goal of getting more people to contribute to writing and reviewing documentation and having more than vague ideas about what is or isn't considered minor items to just leave alone or points of interest to debate. But as much as I would love perfectly written English documentation I try to consciously make an effort to accept things that maybe aren't perfect but are good enough in the interest of having a larger set of contributors with more varied abilities in this area. "It is clear enough" is a valid trade-off to take.
Thanks, though it was meant to be a bit rhetorical.
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).
I'm not following this line of reasoning.
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?
I suspect over half of the questions asked are due to not reading the documentation at all - I tend to get good results when I point someone to the correct terminology and section, and if there are follow-up questions then I know where to look for improvements and have a concrete question or two in hand to ensure that the revised documentation answers.
I'm fairly well plugged into user questions and have recently made an attempt to respond to those with specific patches to improve the documentation involved in those questions. And also have been working to help other documentation patches get pushed through. Based upon those experiences I think this monumental community effort is going to stall out pretty quickly - regardless of its merits - though if the effort results in a new guidelines document then I would say it was worth the effort regardless of how many paragraphs are optimized away.
My $0.02
David J.
pgsql-hackers by date: