[Getting Started] 3rd revision - attn. library authors
I've just checked in the 3rd revision of the Getting Started Guide; see http://boost-consulting.com/boost/more/getting_started.html I'm running out of time to work on this, so at this point I'd like to get feedback only about real problems (i.e. no stylistic issues). Authors of libraries with separately-compiled parts, I need you to send me links to any library-specific pages regarding build configuration so I can finish the list here: http://boost-consulting.com/boost/more/getting_started.html#conclusion-and-f... -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
I've just checked in the 3rd revision of the Getting Started Guide; see http://boost-consulting.com/boost/more/getting_started.html
I'm running out of time to work on this, so at this point I'd like to get feedback only about real problems (i.e. no stylistic issues).
Sorry, but as a former literature major I can't help it: "Start with libs/index.html if you're looking for the whole enchilada." should be in proper English "Start with libs/index.html if you're looking for the beginning of the entire documentation." Otherwise the document is a very good introduction to Boost, and a great addition to the online documentation regarding the library. Congratulations !
Edward Diener <eldiener@tropicsoft.com> writes:
Sorry, but as a former literature major I can't help it:
"Start with libs/index.html if you're looking for the whole enchilada."
should be in proper English
"Start with libs/index.html if you're looking for the beginning of the entire documentation."
As an inveterate stickler for precise criticism, I have to object. What I wrote is proper English; it just happens to use a colloquialism. Informal? Yes, but that's another matter. My writing tends to be very dry, and I think it can only benefit from the rare injection of levity. This phrase doesn't hurt unless it is wildly out-of-step with the tone of the rest of the document, or is going to confuse people who aren't familiar with our slang. IMO, in context, "the whole enchilada" is sufficiently obvious, but if non-native speakers contradict me I'll happily remove it. For that matter, if there is a general outcry against the phrase for any reason, I'll happily remove it. I don't want take it out on the grounds that it's improper, because I don't agree with the premise.
Otherwise the document is a very good introduction to Boost, and a great addition to the online documentation regarding the library. Congratulations !
Thanks :) -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Edward Diener <eldiener@tropicsoft.com> writes:
Sorry, but as a former literature major I can't help it:
"Start with libs/index.html if you're looking for the whole enchilada."
should be in proper English
"Start with libs/index.html if you're looking for the beginning of the entire documentation."
As an inveterate stickler for precise criticism, I have to object. What I wrote is proper English; it just happens to use a colloquialism.
"Proper English" is a relative term, based on the context in which it occurs. When you are writing a technical document you want to be as clear and precise as possible. Colloquialisms tend to blur that preciseness. In the case of "the whole enchilada" you are using a colloquialism which badly blurs what you mean in favor of the idea that the reader should just intuitively understand what you are trying to say. If you do believe that, you should just leave out the expression connected to the explanation entirely, since you are telling the end-user next to nothing by using it except that you can use a colloquialism which generally has a humorous connotation. Years ago people might have used the phrase "the whole kit and kaboodle". Maybe today it is "the whole enchilada" or something even more commonly used. Neither of those phrases go over well in serious technical documentation, and the effort to be precise and helpful to end users. In casual speech, or e-mails most people use such language, but the effort to write technical documentation should set a higher standard. Of course it is your document and your decision, but I think such language is not proper English in its context.
David Abrahams wrote:
Edward Diener <eldiener@tropicsoft.com> writes:
Sorry, but as a former literature major I can't help it:
"Start with libs/index.html if you're looking for the whole enchilada."
should be in proper English
"Start with libs/index.html if you're looking for the beginning of the entire documentation."
As an inveterate stickler for precise criticism, I have to object. What I wrote is proper English; it just happens to use a colloquialism. Informal? Yes, but that's another matter. My writing tends to be very dry, and I think it can only benefit from the rare injection of levity.
I am not a native English speaker, and I want to say that I very much like to see such colloquials interspersed. As long as there are not so much to distract my attention. This is a very good way to improve knowledge of the language on the go. I usually have one of the dictionaries open in my browser so it still is easy listening. Dave, I like your style very much! Roland
David Abrahams writes:
IMO, in context, "the whole enchilada" is sufficiently obvious, but if non-native speakers contradict me I'll happily remove it.
FWIW, I wasn't familiar with the expression and had to look it up. Also, and also FWIW, according to Cambridge International Dictionary of English (http://dictionary.cambridge.org/define.asp?key=90418&dict=CALD), it's an Americanism :). -- Aleksey Gurtovoy MetaCommunications Engineering
Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:
David Abrahams writes:
IMO, in context, "the whole enchilada" is sufficiently obvious, but if non-native speakers contradict me I'll happily remove it.
FWIW, I wasn't familiar with the expression and had to look it up.
Had to because it was unclear, or just because you were curious?
Also, and also FWIW, according to Cambridge International Dictionary of English (http://dictionary.cambridge.org/define.asp?key=90418&dict=CALD), it's an Americanism :).
Yes, believe it or not there's such a thing as "proper American English." -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams writes:
Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:
David Abrahams writes:
IMO, in context, "the whole enchilada" is sufficiently obvious, but if non-native speakers contradict me I'll happily remove it.
FWIW, I wasn't familiar with the expression and had to look it up.
Had to because it was unclear, or just because you were curious?
I guessed that it means something like "the whole thing", so mostly the latter.
Also, and also FWIW, according to Cambridge International Dictionary of English (http://dictionary.cambridge.org/define.asp?key=90418&dict=CALD), it's an Americanism :).
Yes, believe it or not there's such a thing as "proper American English."
I didn't mean to imply that there isn't, I was just noting that the phrase targets a very specific audience: native speakers of American English. For instance, "... if you're looking for the whole thing" would still be colloquial but more "international", if you will. Anyway, it's your call, like I said, all the above is FWIW :) -- Aleksey Gurtovoy MetaCommunications Engineering
Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:
David Abrahams writes:
Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:
David Abrahams writes:
IMO, in context, "the whole enchilada" is sufficiently obvious, but if non-native speakers contradict me I'll happily remove it.
FWIW, I wasn't familiar with the expression and had to look it up.
Had to because it was unclear, or just because you were curious?
I guessed that it means something like "the whole thing", so mostly the latter.
That's reassuring.
Also, and also FWIW, according to Cambridge International Dictionary of English (http://dictionary.cambridge.org/define.asp?key=90418&dict=CALD), it's an Americanism :).
Yes, believe it or not there's such a thing as "proper American English."
I didn't mean to imply that there isn't, I was just noting that the phrase targets a very specific audience: native speakers of American English.
It targets everyone because the phrase is (IMO) amusing and comprehensible no matter what kind of English you were first taught.
For instance, "... if you're looking for the whole thing" would still be colloquial but more "international", if you will.
But not the least bit colorful or amusing.
Anyway, it's your call, like I said, all the above is FWIW :)
Well, it's worth a lot to me to know it didn't actually cause you a comprehension problem :) -- Dave Abrahams Boost Consulting www.boost-consulting.com
participants (4)
-
Aleksey Gurtovoy -
David Abrahams -
Edward Diener -
Roland Schwarz