Re: [PATCH] Various documentation typo/grammar fixes

Tom Lane-2 wrote
> Kevin Grittner <

> kgrittn@

> > writes:
>> Patch 1 pushed, with each fix back-patched as far as the error
>> exists in supported releases.  I held off on patch 2 -- partly
>> because I spotted at least one case where things weren't quite
>> right, partly because there's so much I haven't had time to go over
>> it in sufficient detail, and partly because commas are omitted so
>> consistently where most style guides want them that I thought
>> someone might want to argue that this was an intentional style
>> choice and should be preserved.
>
> I would argue against applying patch 2 at all.  I think it's what
> John McIntyre (http://www.baltimoresun.com/news/language-blog/)
> would call peeverism.  If there are any places where the extra
> commas/periods actually add anything to clarity, then sure, change
> those places --- but doing it only because some style guide tells
> you to is not the way to approach the issue.  We're writing English
> not C code here, and so there is no single standard of correctness.

Writing C code, aside from purely syntactic concerns, does not abide by a
single standard of style correctness either yet this project does have a
style guide that is to be adhered to.  I do not think it to be a bad thing
to accept a style guide as reference for the documentation as well.

My main objections are:

1) we are simply treating symptoms
2) we are introducing a decent amount of not-meaning-enhancing change

But if one is going to adopt a lassiez-faire attitude then whether or not
patch 2 (and 3) is applied should make little difference.

And given the surgical nature of the update in question the commit history
of the documentation is practically unaffected.

As a matter of internal consistency, and also for adherence to "best
practices", I'd vote to apply all three patches once fully reviewed - though
by the same logic above if we miss a few items the overall impact on the
qualify of the documentation will still be positive and the incorrect
locations will likely still be understandable.

I don't expect writers to be able to keep straight all of the style rules
that we'd like to try and adhere to but having good existing documentation
will make it more likely for new content to conform.  The goal would be to
let them focus on writing but then have some kind of editing process - which
is what is going on now - to aid in polishing the final publication.

David J.




--
View this message in context:
http://postgresql.1045698.n5.nabble.com/PATCH-Various-documentation-typo-grammar-fixes-tp5816078p5817040.html
Sent from the PostgreSQL - docs mailing list archive at Nabble.com.