Re: [DOCS] [PATCH] Various documentation typo/grammar fixes
Marti Raudsepp wrote: > All updated patches attached, per our previous discussion. > Patches 1-2 are ready, 3 can be discarded unless someone else > chimes in. 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'm also not sure that it should be back-patched as the outright errors were -- it does seem like more of a style issue than most of the things in patch 1 were, which included clear misspellings, accidentally repeated words, and incorrect choices of indefinite articles. The remaining error I mentioned above was an occurrence of a parenthetical remark which started with "e.g.," and ended with ", etc."). The Chicago Manual of Style says that you can use one or the other, but using both is redundant and should be avoided. > Do you think it's worth doing a run over developer documentation > (README files) and code comments too, or is that a waste of time? Some README files could use a lot of attention; I'm just not sure that fixing a few misspelling, repeated words, or grammar errors makes enough of a dent in what is needed to be worth it. -- Kevin Grittner EDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] [PATCH] Various documentation typo/grammar fixes
Kevin Grittner 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. regards, tom lane -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] [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. -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
