Talk:Paradoxes of API Design

From APIDesign

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.

--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.

--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.

--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.

--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.

--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.

--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.

• Tracy Chapman's Promises.

--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.

--Dmkoelle 03:27, 21 April 2008 (UTC)