New page: Most of the text in this introductory section, especially in the section "The Fearless Physics of The Renaissance", is too abstract and philosophical to be appropriate in a book of this so...
New page
Most of the text in this introductory section, especially in the section "The Fearless Physics of The Renaissance", is too abstract and philosophical to be appropriate in a book of this sort.
--[[User:AdamDingle|AdamDingle]] 17:00, 20 April 2008 (UTC)
The introduction here is too talky. The reader will want to continue delving into API; as fun as waxing philosophic may be, I think it impedes the flow here.
--[[User:Dmkoelle|Dmkoelle]] 03:18, 21 April 2008 (UTC)
'''Done: 9718e02b9cc9'''
In my opinion the term "doublethink" is a bit odd here and only serves to confuse the reader. The first couple of paragraphs are a little confusing, since the first paragraph says that common API advice is either to expose a stable API *or* keep it private, while the second paragraph talks about advising to stabilize an API *and* require it to vanish (your words "at the same time requiring" imply "and", not "or").
Your essential point in this section is that unlike many software systems, which go through alternating periods of stability and instability throughout their lifetimes, an API is first unstable but then switches to being stable forever. You explain that point well enough in the third and following paragraphs, so I might just skip paragraphs one and two as well as the term "doublethink" here.
The section "Architecture Reviews at NetBeans" seems fairly lightweight and anecdotal; I might skip it as well.
--[[User:AdamDingle|AdamDingle]] 17:08, 20 April 2008 (UTC)
This section doesn't make much sense to me. Doublethink is believing 2 things simultaneously. What you're talking about is making a choice _between_ 2 things. It seems like the point you're making with this section is just that the first release is an important milestone, and the API design goals before and after that release should be very different. I think you made this point several times earlier in the book, and this whole section seems extraneous.
--[[User:Richunger|Richunger]] 02:50, 24 April 2008 (UTC)
'''Done: 9718e02b9cc9'''
I think the comparison between a API development supervisor and an airport security agent is a little steep. "How similar this is" seems like quite a stretch, particularly to people who might be sensitive to recent, unfortunate hijackings.
--[[User:Dmkoelle|Dmkoelle]] 03:23, 21 April 2008 (UTC)
Second to last paragraph of this section, before "Overcoming the Fear" heading: "I am glad to have evidence of my foresight..." It comes across as though you are planning to say "I told you so" to the developers, although I am not sure you meant it this way. It would be more productive to say that collecting such evidence helps us to constantly improve and learn from our mistakes.
--[[User:TomWheeler|TomWheeler]] Wed Apr 23 20:38:48 CDT 2008
'''Done: b8785512bd80'''
Your paragraph about the knights' rendezvous in Paris seems like a tangent and is overly general; I might skip this. Your text about the Czech National Bank also seems to ramble a bit.
"Like the song says": which song? I don't think this is a song that most readers will know.
* [http://en.wikipedia.org/wiki/Tracy_Chapman Tracy Chapman]'s Promises.
--[[User:AdamDingle|AdamDingle]] 17:11, 20 April 2008 (UTC)
Ditto Adam.
Also, I feel there's actually a lot of good stuff in this section, but it gets a little lost in the paragraphs. For example, "lack of time" is four sentences into one paragraph. I wonder if an explicit listing of fears might be more useful, because one can peruse it quickly and undoubtedly find one or more that apply to them.
--[[User:Dmkoelle|Dmkoelle]] 03:27, 21 April 2008 (UTC)
--[[User:AdamDingle|AdamDingle]] 17:00, 20 April 2008 (UTC)
The introduction here is too talky. The reader will want to continue delving into API; as fun as waxing philosophic may be, I think it impedes the flow here.
--[[User:Dmkoelle|Dmkoelle]] 03:18, 21 April 2008 (UTC)
'''Done: 9718e02b9cc9'''
In my opinion the term "doublethink" is a bit odd here and only serves to confuse the reader. The first couple of paragraphs are a little confusing, since the first paragraph says that common API advice is either to expose a stable API *or* keep it private, while the second paragraph talks about advising to stabilize an API *and* require it to vanish (your words "at the same time requiring" imply "and", not "or").
Your essential point in this section is that unlike many software systems, which go through alternating periods of stability and instability throughout their lifetimes, an API is first unstable but then switches to being stable forever. You explain that point well enough in the third and following paragraphs, so I might just skip paragraphs one and two as well as the term "doublethink" here.
The section "Architecture Reviews at NetBeans" seems fairly lightweight and anecdotal; I might skip it as well.
--[[User:AdamDingle|AdamDingle]] 17:08, 20 April 2008 (UTC)
This section doesn't make much sense to me. Doublethink is believing 2 things simultaneously. What you're talking about is making a choice _between_ 2 things. It seems like the point you're making with this section is just that the first release is an important milestone, and the API design goals before and after that release should be very different. I think you made this point several times earlier in the book, and this whole section seems extraneous.
--[[User:Richunger|Richunger]] 02:50, 24 April 2008 (UTC)
'''Done: 9718e02b9cc9'''
I think the comparison between a API development supervisor and an airport security agent is a little steep. "How similar this is" seems like quite a stretch, particularly to people who might be sensitive to recent, unfortunate hijackings.
--[[User:Dmkoelle|Dmkoelle]] 03:23, 21 April 2008 (UTC)
Second to last paragraph of this section, before "Overcoming the Fear" heading: "I am glad to have evidence of my foresight..." It comes across as though you are planning to say "I told you so" to the developers, although I am not sure you meant it this way. It would be more productive to say that collecting such evidence helps us to constantly improve and learn from our mistakes.
--[[User:TomWheeler|TomWheeler]] Wed Apr 23 20:38:48 CDT 2008
'''Done: b8785512bd80'''
Your paragraph about the knights' rendezvous in Paris seems like a tangent and is overly general; I might skip this. Your text about the Czech National Bank also seems to ramble a bit.
"Like the song says": which song? I don't think this is a song that most readers will know.
* [http://en.wikipedia.org/wiki/Tracy_Chapman Tracy Chapman]'s Promises.
--[[User:AdamDingle|AdamDingle]] 17:11, 20 April 2008 (UTC)
Ditto Adam.
Also, I feel there's actually a lot of good stuff in this section, but it gets a little lost in the paragraphs. For example, "lack of time" is four sentences into one paragraph. I wonder if an explicit listing of fears might be more useful, because one can peruse it quickly and undoubtedly find one or more that apply to them.
--[[User:Dmkoelle|Dmkoelle]] 03:27, 21 April 2008 (UTC)