== General notes about the first version of the book by [[User:TomWheeler|Tom Wheeler]] ==

The following are some comments or observations which apply to the book in general, rather than to any specific chapter.

* Brevity
Most of the material is much more verbose than required. In many cases, the important point is conveyed in just one or two sentences and then elaborated on for several more without adding any significant information.

I look at the K&R "C Programming Language" book as a model for technical writing. It's only 176 pages long (excluding the reference section) yet completely describes an entire programming language. Joshua Bloch's "Effective Java" is another example of this and is also a great study in how to mix theory and practical information.

* De facto
You often write things like, "this class is de facto not part of the public API." It would be more natural in American English to replace "de facto" with "by default".

* Use of Ellipses
You use ellipses (three dots) too often in my opinion. You typically do not have a space after the ellipses but before the following word as you ought to have.

* Periods/Commas inside quotes
You tend to put periods and commas outside of quotation marks, which is incorrect. Here is a proper example: Tom Wheeler said, "blah blah blah."

* Long passages of code
They should be truncated to show just the minimum needed to illustrate the point. If you must include long passages of code, you should at least format the important parts differently so it will be more obvious what we should be looking at specifically.

* Practical API design example
One of the best computer books I have read recently is "Unit Testing in Java" by Johannes Link. What I like about it is that it makes it very clear how to apply the advice he's giving. He does this by starting off with a very simple example of a program and shows how to test it, then updates the test to handle new scenarios as the program grows more complicated. It would be very interesting if your book did something similar through the entire lifecycle of a simple API: first you show how to design it, then implement it, then test it, then document it and then enhance it to satisfy new requirements. The API Fest examples did do this somewhat towards the end, but a consistent theme throughout the book would help tie things together.

--[[User:TomWheeler|TomWheeler]] Wed Apr 23 20:38:48 CDT 2008

== Comments by [[User:Richunger|Rich Unger]] ==

Who is your audience? Is it programmers who are just starting on API design? It reads more like a treatise meant to convince people who think they're already API-design experts that your way is better. Don't you have a user story for this book? ;-)

If you want to introduce people to API design, you need to front-load it with examples of good and bad APIs (before the philosophical stuff, which should be briefer). Your reader will have little to no experience writing APIs, but loads of experience using them. In the first section, get him to say, "oh, yeah, i like that kind of API" and "yeah, I've used APIs like that. They're really frustrating." If they agree with your assessment of which APIs are good and which are bad (from their experience), they're more likely to want to know your rules for building good ones.

In other words, it's always better to start well within your reader's comfort zone.

I like the way you introduce the concept of cluelessness. The anecdote of the different phases of writing a web site is effective.

--[[User:RichUnger|RichUnger]] Thu Mar 27 21:50:09 PDT 2008


In this particular section, I'd cut everything after "Theories are products of science..." and begin again with "This part of the book..."

Overall, I agree with the sentiments here. There's a lot of fantastic content here, and I personally learned a lot that I hope to apply in my new job. However, I feel that all that I learned, I waded through a lot of text to get to. Your philosophy on API design will come through with the instructive parts of the book. The extensive background is unnecessary and will not capture readers' interests. You often repeat points unnecessarily, to get your readers 100% on the same page as you. Strive for 99%, which will allow you to cut a lot of text ;-)

--[[User:Richunger|Richunger]] 02:45, 24 April 2008 (UTC)



== Comments by [[MartinRinard]]



Hi Jaroslav. I read part1.pdf. There is some very good material in
here and I think it has the potential to be a very important
contribution. However, you need to make some pretty substantial
changes for it to realize its potential.

You should first think about who your potential audience is and why
you are qualified to address them. Your potential audience is people
who are concerned with developing APIs in one way or other - people
who are actively developing an API, people who are providing feedback
and criticism on the API as it is under development, or people who are
requesting extensions to the API. You are qualified to address them
because you have been through the process already and learned things
you can learn only through experience. People will read the book
almost exclusively to gain the benefit of your experience through just
reading the book instead of by having to do what you did.

Note that you need to provide little motivation for your
topic. Everyone interested in reading the book will be primed for its
content. Everyone will have used an API, will buy into the basic
notion that an API is an inevitable part of the path to building large
systems, and will recognize that APIs are difficult to get right,
cause problems when they are not perfect, and are in general in need
of improvement. So you need to provide little or no motivation for
your topic. You need to get to the point as soon as possible.

Your goal in writing the book should be to allow your audience to be
as clueless as possible about building APIs while still developing a
reasonable API. Your current structure tells them too many things they
1) can do without and 2) will most likely want to do without. Here is
some feedback on each chapter:

Chapter 1:

This chapter takes too long to develop. It is also too apologetic.
It also has too many analogies. You should make the points in this
chapter as simply and quickly as possible. Here are the points I
see:

# APIs are important for building systems.
# I have spent a lot of time building the NetBeans APIs and learned a lot.
# Designing APIs is different from developing software.
# Read this if you are involved in the development of an API and want to make a good API.

Punt all the analogies, long verbiage, and justification.
Make the chapter as short, abrupt, and to the point as
possible. I would say you could put the essential content
in two pages. In particular:

# Don't address the question of why another design book. Just say this book will help you design APIs.
# Drop the house analogy and star analogy in Section 1.1. Write directly to the point. Everyone reading the book will know more about software development than building a house or astronomy and will therefore get more out of a direct attack on the topic rather than an approach based on an analogy. It will not come as a surprise to any of your readers, for example, that APIs need to stay around for a long time.
# In Section 1.2, just say that if you are designing an API (which includes writing code for anyone to use) you should read this book.

# In Section 1.3, say the details have been developed for Java, but the basic principles apply to most languages. Make this Section shorter. Also drop the whole discussion of virtual machines.

You may want to rewrite this part to make it clearer and more
direct. In fact, I would strongly urge you to do so.

Part 1

I don't know what this part is accomplishing here. Try to eliminate it/incorporate the basic concepts into the rest of the book.

Chapter 2:

This chapter violates the basic cluelessness principle: nobody
reading the book for the first time will understand why they need to
know this (and in fact, they probably don't if all they want to do is
design better APIs). I agree that the material is interesting. Better
to put it far back in the book after they have seen some more concrete
material. As it stands, you will lose large numbers of readers in
this part. Also, this material is not in your area of expertise and
comes across as shallow, even naive, in comparison with subsequent
chapters where your expertise comes across very strongly.

Find a way to get the basic concepts of API design (backwards
compatibility, cluelessness) across in a much shorter and more direct
way. Your audience needs these basic concepts to understand the book,
but you need to get it to them as quickly and directly as possible.
Bear in mind that your audience is primed for a direct treatment of
these two concepts (although you need to be a bit more artful in the
way you introduce cluelessness).

Also, you need a quote from Alfred North Whitehead:

"Civilization advances by extending the number of important operations
we can perform without thinking of them."

(Page 61, An Introduction to Mathematics, Alfred North Whitehead,
available at books.google.com)

By the way, thanks for your piece on my OOPSLA talk - it is nice to know
that the talk had an impact of some kind!

Chapter 3:

The book improves dramatically at this point because you are
speaking about things you are clearly an expert on. I would still try
to make the chapter more direct and to the point. You could get by
with substantially less on version numbering, for example, because
your target audience should be largely familiar with many of the
concepts.

Chapter 4:

The material is good here, once again because you are an expert in
the area. Same for Chapter 5.

General comment:

You may wish to rethink the book to make it a flat sequence of
hints, much like Effective Java or Design Patterns. The success of
these books is that they support cluelessness - the reader can pick up
the book, read any number of short segments, and get something out of
it. The reader does not have to think and nobody is trying to get
across general concepts that the reader may have to struggle with. The
reader can read just as much or as little as they want, then pick the
book up later. The success of these books shows that there is a need
for this approach.

I am not saying your book needs to do this. But it may very well be
more successful if you just come across with a list of very specific,
very pragmatic API design hints, each illustrated with an example from
your experience. The only discussion of theory and principles would
come (if at all) only at the end of the book where people can easily
be unaware of it if they wish to do so. This approach would make the
book extremely accessible to your audience. I would consider this
approach seriously.

I am sending this to you directly because I am not sure if it
is appropriate to post it on the Wiki. Please let me know if you
would like me to do so, or if there is something in this feedback
that it would help for me to clarify more.

Best Regards,
Martin

Hi Jaroslav. A few more comments on the Part 1 stuff.

# You could largely ameliorate the impact of having the theory right up front by providing a road map to the book for potential readers. The road map would provide several sentences for each chapter and a sentence or two for each section within each chapter summarizing the key message of the chapter or section. No rationale, no explanation, just the content. Readers can then use this to get a quick overview of what is in the book. They can also use it to move quickly to the part of the book that they most want to read and to skip those parts that they find less intuitive.

# I think you are fighting a losing battle if you expect API designers to approach the task with more rationality than any other task they undertake. There are lots of developers building APIs in industry, and most of them simply want to get on with their job and get it done. They are going to be open to advice if it is clear from the very beginning how that advice is directly relevant to their task and if they perceive every piece of information as useful to them. The roadmap I mention above is one way for them to find this information for themselves.

In any case, I think the road map should help the readers
substantially and make the book more accessible and useful to a broad
audience with many different viewpoints and needs.

Best Regards,
Martin

== [[User:AdamDingle|AdamDingle]] notes ==

Jarda,

I've now finished reading your entire book and so I'll put some overall feedback here (for lack of a better place).

You obviously have years of experience in the trenches of API design for a large, complex and evolving project and it's great that you've decided to distill your wisdom into a book. Your book's strength is that it provides lots of specific examples and advice in Java. Some other software engineering books attempt to be language-independent, but many API design aspects are language-specific and so it's really useful for the audience of your book (Java programmers) to see many Java examples. You have numerous valuable insights about backward compatibility and about modular and testable API design, some of which I hope to incorporate into my own programming projects.

Your book's primary weakness is that it too often rambles into personal anecdotes, vague philosophical speculations and NetBeans-specific details. I have a challenge for you: edit your book to reduce its length by a factor of two. Yes, that's right: reduce the page count by half. That may seem painful, but believe me: ''it will be a better book''. If you don't believe me, ask the other reviewers whether they agree. The classic software engineering texts, such as Effective Java and Design Patterns (both of which you mention at the very beginning of your book) are shorter than yours and are written in a much more concise style, and you'll also need to write more concisely if you hope to join them. Generally speaking I found the middle third of your book to be the most focused and useful, and I suspect that a shortening of your text would include a bit more text from that section than from the others.

--[[User:AdamDingle|AdamDingle]] 17:39, 20 April 2008 (UTC)