| From: | Peter Geoghegan <pg(at)bowt(dot)ie> |
|---|---|
| To: | Bruce Momjian <bruce(at)momjian(dot)us> |
| Cc: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Heikki Linnakangas <hlinnaka(at)iki(dot)fi>, Joshua Drake <jd(at)commandprompt(dot)com>, PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org> |
| Subject: | Re: Optimizing the documentation |
| Date: | 2020-12-17 19:19:19 |
| Message-ID: | CAH2-WzkM8qq9W2CYmz841YNsdz466Qdqh-jRZBiJCC0o907YRQ@mail.gmail.com |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-hackers |
On Thu, Dec 17, 2020 at 7:42 AM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> I agree a holistic review of the docs can yield great benefits. No one
> usually complains about overly verbose text, but making it clearer is
> always a win. Anyway, of course, it is going to be very specific for
> each case. As an extreme example, in 2007 when I did a full review of
> the docs, I clarified may/can/might in our docs, and it probably helped.
I think that the "may/can/might" rule is a very good one. It
standardizes something that would otherwise just be left to chance,
and AFAICT has no possible downside. Even still, I think that adding
new rules is subject to sharp diminishing returns. There just aren't
that many things that work like that.
--
Peter Geoghegan
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Tom Lane | 2020-12-17 19:28:16 | Re: [HACKERS] [PATCH] Generic type subscripting |
| Previous Message | Peter Geoghegan | 2020-12-17 19:12:20 | Re: [PATCH] nbtree: Do not show debugmessage if deduplication is disabled |