←Older revision |
Revision as of 05:12, 14 June 2008 |
Line 21: |
Line 21: |
| * Grammar: last paragraph, your tenses are mixed. I would suggest: "Since then, I've known the need for information relating to API design is real. The memory of that presentation has encouraged me whenever I've begun to lose motivation while writing this book. It has helped to remind me that the rules for proper API design that we've discovered need to be documented. | | * Grammar: last paragraph, your tenses are mixed. I would suggest: "Since then, I've known the need for information relating to API design is real. The memory of that presentation has encouraged me whenever I've begun to lose motivation while writing this book. It has helped to remind me that the rules for proper API design that we've discovered need to be documented. |
| --[[User:RichUnger|RichUnger]] | | --[[User:RichUnger|RichUnger]] |
| + | |
| + | [[AndreiBadea]] Smalltalk and not SmallTalk |
| + | |
| + | I can hardly agree that our APIs are "relatively consistent". |
| + | This is simply not true when you compare them to APIs for similar purposes. |
| + | A brief examination of just the things that can be installed in XML layers |
| + | shows a huge archaeological spread of different styles and techniques, many now deprecated. |
| + | * OK. Explained a bit: '''6e521d0cd6ea''' |
| + | |
| + | --[[User:JesseGlick|JesseGlick]] 02:51, 25 March 2008 (UTC) |
| + | |
| + | |
| + | * Wording: Pg 6, Para 3: Change "Increasing this asset" to "Increasing the value of this asset" |
| + | * Wording: Pg 6, Para 3: You use the phrase RICH USER BASE, and the paragraph is about money. I think this confuses the meaning of the word RICH - I think you mean to say "extensive user base" as opposed to "wealthy user base". Change the word RICH to something else (like EXTENSIVE). |
| + | * Wording: Pg 6, Para 3: People cringe at the word MONETIZE. Change it to BENEFIT FROM or something similar. Money is not the only bottom line, after all. |
| + | |
| + | --[[User:Dmkoelle|Dmkoelle]] 20:26, 26 March 2008 (UTC) |
| + | |
| + | |
| + | * (spelling) pg. 5, last para: "a bit more engineering design" => "a bit more engineering-driven design" |
| + | |
| + | --[[User:AdamDingle|AdamDingle]] 22:45, 27 March 2008 (UTC) |
| + | |
| + | * I felt the analogy in the first paragraph went on for too long. |
| + | * Punc: Pg 3, Para 1 (i.e., first full paragraph) - should be semicolon (;) before HOWEVER |
| + | * Delete: Pg 3, Para 2: Don't need "Well, obviously." sentence |
| + | * Pg 3, Para 2: "forever" is such a strong word. I was going to recommend saying "almost forever", but I think that weakens the "APIs are with us forever" line, so keep it :) |
| + | * Delete: Pg 3, Para 3: I didn't understand the sentence, "However, one cannot rely on that." THAT seems not well-defined, and I'm not sure why someone would rely on almost invisible functionality. I think you can remove this sentence. |
| + | * Punc: Pg 3, Para 3: End of sentence has an extra period - remove the one after the quotation mark. |
| + | * Punc: Pg 4, Para 0 (i.e., the paragraph that started on Pg 3): need comma after HOWEVER |
| + | * Delete: Pg 4, Para 2: In the sentence that begins with "For example", delete HOWEVER |
| + | |
| + | * End of section: At this point, it sounds like API design is only about backwards compatibility, and that this is the only differentiating factor between this book and other design books. I suspect there's a lot more that you're going to reveal about API Design that will make the content in this book different from other design books. If you can put some of those in, perhaps at the expense of some of the verbose analogy, that might be beneficial. |
| + | |
| + | --[[User:Dmkoelle|Dmkoelle]] 20:21, 26 March 2008 (UTC) |
| + | |
| + | This section is really long-winded. |
| + | The universe analogy makes sense in the latter parts discussing physics, |
| + | but just seems like excess text in the earlier parts talking about stars. |
| + | |
| + | --[[User:JesseGlick|JesseGlick]] 02:36, 25 March 2008 (UTC) |
| + | |
| + | * (grammar) pg. 1: "the existing design books" => "existing design books" |
| + | * (grammar) pg. 3, para 1: "than a change to a one line bug fix" => "than a one-line bug fix" |
| + | * (grammar) pg. 3, last para: "APIs are like stars...": why are you quoting this? Did someone else say it? If so, who? If these are your words, there's no need to quote. If you want to emphasize this point, use italics. Quotation marks should not be used for emphasis; see, for example, http://en.wikipedia.org/wiki/Quotation_mark#Emphasis_.28incorrect_usage.29 or http://www.dailywritingtips.com/punctuation-errors-quotation-marks-for-emphasis/ . |
| + | * (grammar) pg. 5, para 3: "once an API star is discovered...": again, why quotes here? |
| + | |
| + | --[[User:AdamDingle|AdamDingle]] 22:44, 27 March 2008 (UTC) |
| + | |
| + | * Page 3, para 3. "If the world behaved like that, it would class with our understanding of the known universe." Our understanding of the world comes from the what we observe, so this does not make sense. Our understanding would simply change to accept what we see. |
| + | ** Very good observation. I've changed that to "understanding of the universe as we perceive it today". |
| + | * I agree with Jesse. This text about stars is all deep and interesting, but IMHO does not really fit in a book about API design. |
| + | |
| + | --[[User:TomWheeler|TomWheeler]] Thu Mar 27 21:16:22 CDT 2008 |