ThanksEveryone

From APIDesign

Current revision

A book is unlikely to be written by single person. Even it has just one author, just like TheAPIBook has Jaroslav Tulach, it is always work of a team. This page is my attempt to enumerate those who helped me and provide some story associated with them, so their contribution stands out in the real light.

Geertjan and Patrick

First and foremost I need to thank GeertjanWielenga and PatrickKeegan. I handle English language well enough to survive in English speaking country, to write emails and online documents, however language for book needs more than that. It needs to be poetic and also correct.

Geertjan made this happen. He digged through all of my text and converted it from my basic and sometimes not really correct English to real English ready to entry the pages of real, printed book. This was really essential work. Without it, the book would never be published. Thanks, Geertjan.

Surprisingly, Geertjan was very helpful in one, originally unexpected way: He was perfect for identifying places of the book where the topic become extra ordinary complex and not clearly understandable. As soon as that happened, Geertjan's translation started to loose sense. This was a perfect indication for me that some parts of the text need to be rewritten and polished. Usually I just read the text provided by Geertjan and as soon as the new sentence said complete opposite compared to my original, I knew I was not exact enough and I expressed myself insufficiently. Thanks Geertjan for this kind of help as well.

Patrick was usually reading the text after Geertjan and watched for inconsistencies, structure and ensured that the chapter, section and paragraph organization is reasonable. This was not really easy. I admire the writing style of Hrabal's books, where the words flow like a river and as soon as you start reading, there is no way to stop, till the chapter is over. I tried to do this in my book as well, just write, type the words, not looking back until the topic is fully described. This worked fine, but of course, the language was far from perfect and needed a lot of re-organization and structural changes. Patrick provided them and I am really thankful to him for doing that.

Originally, according to the deal with my publisher, both Patrick and Geertjan were supposed to be translators only. They were supposed to convert my English to colloquially spoken one. However they did much more than that. At the end of our work, Patrick saw a mail from the publisher describing his work as translation and he reacted: "If I knew that I am doing just a translation, I would not be that nervous and I would not need to try so hard." I am really glad Patrick and Geertjan did much more than just translation and I was really happy to see following note from Susannah processing the text later: thanks also to your translators, who did a great job on the text even before it came into my hands!

Apress

As you may already now, the base for the book was a set of notes, emails and journal entries collected over last ten years. That is good start, but still it is far away from a book. That is why, the first thing I did was to write the Prologue, the Outline and send it too few publishers. I am really glad that Apress was the most open one. I can imagine it was not easy decision to support this project. At the end this was the first book on the topic of API design and nobody could exactly estimate its impact. I am really glad Dominic Shakeshaft gave his go at the end. Thanks, Dominic.

Clay Andres

Clay was my first Apress contact. He walked with me through the outline of the book, ensuring it is put into proper context. He also read the book's text and verified that it makes some sense. An interesting story I remember is related to his advice to use a special quote from another book he was editing to support the idea of Cluelessness:

"Many clocks rely on an elaborate system of gears to tell time, but humans see very little of what goes on inside a clock. We don't have to figure out the time from the positions of the gears; we can look at the hands on the clock face. In other words: the gears are important to the clock, but they're not important to us."

I like the quote, however using it felt like stealing. Anyway I did incorporate it into some version of the TheAPIBook and asked Clay what he thinks. He said that it is fine, if I attribute this quote to Andrew Dupont and his book on Prototype and script.aculo.us. Suddenly I realized that stealing is not for free. Immediately you become partner in a crime. As I felt uneasy to reference a book I have not read, I rewrote the quote to meantion GPS. However I still like it very much, as it greatly explains the concept of Cluelessness. Thanks Clay for finding such a nice quote!

Kylie Johnston

As soon as Clay was satisfied with the text, he passed me to hands of Apress production team, represented by Kylie. Kylie acted as a single access point hiding all the complexity of book publishing from me. Whenever I needed anything, I had to contact her and she would handle the rest. The only exception were Susannah and Ellie, which I talked directly. Thanks Kylie for isolating me from the gory details of book publishing and finding Susannah and Ellie.

Susannah Davidson Pfalzer

Susannah was continuing in the work started by GeertjanWielenga and PatrickKeegan. She polished the text of the book to be more readable and not contain stupid errors. Susannah is author of the quote valuing Patrick and Geertjan for their good work, however that does not mean she would have nothing to do. Thanks to her, the book is more concise (as she eliminated all useless however, in spite of, often, always, etc. added by me), more personal (Susannah replaced for example did not with didn't) and more consistent (Susannah always made sure to fully spell a technology name, before using its acronyms).

Funny situation happened once, when I complained about my name being unreadable. Susannah tried to comfort me by pointing out that her last name is hard to read for English speakers as well. That made me feel better for a while, but only until I realized that Susannah also has a middle name which compensates this. Anyway, thanks Susannah for making TheAPIBook better book.

Ellie Fountain

Ellie is responsible for final layout of the pages. So if you find the book visually attractive, it is the result of Ellie's work. She always sent me a PDF and I was supposed to review it. Usually I could not believe my eyes when seeing it! The words stayed the same, but now they were more beautiful, printed in better font and organized in a way that was just crying: Print me! Print me! The only problems, I discovered, concerned the formatting of code samples and usage of ISO-8859-2 characters. Both of which somehow vanished from my original material. Quite a small problems given the size of the formatting task. Thanks Ellie for creating pages that look so nice.

Reviewers

When the first version of TheAPIBook was written, and corrected by Geertjan and Patrick, we needed few experts to review the content and catch and help eliminate silly mistakes in code samples, terminology, etc. With a little help from Geertjan I've assembled an invitation, send it to few selected individuals. The following guys generously accepted to to take a look at TheAPIBook. I'd like to thank them all, as I believe that without their help, the book would not be as good as it is now.

AndreiBadea

I wanted Andrei to be the reviewer for few reasons. He works on NetBeans, he knows the style and processes we use to develop APIs, he also knows how to design APIs. However he also likes to argue about everything. I really mean argue, not complain. Except rare occasions, his comments are rational, useful and sharp. It is useful to think about them, evaluate them. I was sure his comments to my book will be exactly like that: sharp, valuable and worth considering.

Indeed this was true. Andrei provided a lot of comments to various code samples, their formatting and code style consistency. I could argue with him that the internals of API do not matter, that the code inside the methods bodies does not need to be well formatted, that it only needs to work. No luck. He literally forced me to rewrite almost all the examples to be nicer claiming that such inconsistencies are not present in Effective Java at all. Thanks Andrei for spotting so many issues and making most of the code samples better.

An interesting point of view can be obtained speculating about reasons why Andrei accepted being a reviewer. Once I mentioned to him that I'd like Josh Bloch to be the reviewer as well. At the end this did not work out, still that point of time might be the moment when Andrei decided to help me: My name starts with B, his name starts with B, imagine I would be printed next to Josh in a single book! Sorry Andrei, that I did not manage to make this happen, and take this paragraph as my apology. Enjoy being mentioned next to Josh at least in one paragraph!

AdamDingle

As you may know the roots of NetBeans can be traced to 1995, when seven of us, students of Faculty of Mathematics and Physics at Charles University in Prague needed to finish a compulsory student project and decided to create a Delphi for XWindow system. The idea was there, however we needed a guidance. A teacher that would lead the project. We quickly found out that no Czech teacher is fool enough to try to lead us. Luckily, we knew Adam, a visiting professor not knowing exactly what it takes to lead seven students and their never-ending work. That is why, when Adam agreed, he became the grand father of NetBeans. Without his help we would not have NetBeans, and I could never finish TheAPIBook. Thanks Adam.

When Adam returned back to U.S., he disappeared from our radar for few years. However at the end of last year, he re-appeared on our mailing list and confessed to use NetBeans IDE. I was really glad to see him and I thought, OK, it would be very nice to get Adam to be a reviewer. He helped start NetBeans and now he can also review the wisdom we generated over the years. I think it was a great choice to invite Adam. Although he is emotionally attached with the project, he does not know anything about its organization, about its code and about its APIs, as such he can play a perfect role of patient external reviewer. He did that perfectly. I remember getting comments like: "this section is too much NetBeans centric, this one is not generic enough". Based on this advice I rewrote a lot of the text to not mention NetBeans at all, or at least explain that the topic is generic enough. Thanks Adam, for making the content of TheAPIBook more generally acceptable.

DaveKoelle

In the scale of our reviewers, we needed some really skilled Java API designer, moreover one that would not be connected to NetBeans at all. GeertjanWielenga recommended Dave, the API design guru behind JFugue musical library. I can hardly imagine someone better playing Dave's role. He acted like real API designer. Skilled, fast, sharp in his reviews and always ready to jump to the gory details of individual code samples. I remember Dave sending comments like Common, I do not need you to tell me what is API, I already know it, just show me the real API code! Sure, Dave, you designed a lot of APIs, it is easy for you to understand the basics, but we need to get everyone on the same starting line, so please bear with me, you'll get what you want!

As Dave received more and more chapters, his complains slowly fade away. However, as Dave is typical API designer, they were not replaced by clamours of happiness. For a few weeks I was not really sure whether Dave really liked the book or not. However when we met during JavaOne 2008, he said something like: Chapter 18, Extensible Visitor Pattern Case Study is really nice summary of all the content of the book, all the advices suddenly emerged and played very nicely together. I am glad for these words. I was not really sure if the chapter 18 is not too complex, however since Dave's comment I know it is not. Thanks Dave helping me realize that!

MartinRinard

Martin is the inventor of term Cluelessness, at least in my eyes. When I saw his presentation at OOPSLA 2006, I was amazed and shocked. His advices were so ugly, but so true, that I could not stop thinking about them. I was thinking about relation between reliability and Cluelessness, about importance of testing and also about the role APIs play in the attempt to increase Cluelessness while improving quality of our applications. At that time I realized that Cluelessness is great meta principle that allows us to evaluate whether an advice is good or not. If something allows people to achieve more while knowing less, then the thing is good. Thanks Martin for inventing such meta principle!

An interesting moment occurred when Martin finished reading first half of the book and said: Your book talks about Cluelessness, but it cannot be read in clueless mode itself! A perfect observation, which I knew somewhere in my brain, but I did not realize it until Martin revealed it. Yes, I love Cluelessness, I want to see Cluelessness everywhere in software development. However when thinking about it and describing it, I automatically applied the like to be scientific methods I learned at European Universities: Theory first, practical applications later. As a result this book does not teach how to design APIs cluelessly, with as little understanding as possible. Instead it sees properly designed APIs as a tool to help other developers to practice Cluelessness. However the API designers themselves need to think about what they do quite a lot.

Martin, as the inventor and great propagator of Cluelessness naturally expected this book to be written in clueless mode, for people in hurry, without need of deeper understanding. This resulted in false expectations, which could not be satisfied by TheAPIBook. I'd be glad to advice to design APIs cluelessly, however I still do not know how to do it properly. That is why I at least tried to set the reader expectations right as soon as possible and warn and straight things up. Thanks Martin for pointing this out, hopefully the changes I've made according to your suggestions will prevent wider disappointments due to readers' false expectations.

Rich Unger

Rich is long time NetBeans Platform user and as such he had to go through all the suffering associated with using NetBeans APIs. He started to use NetBeans platform in version 3.2 or so, which was possible, but hard. In fact there was no support from the NetBeans IDE for developers like Rich. Together we tried to fulfill the need for this by giving frequent presentations describing the necessary tricks when using the NetBeans Platform. These presentations stop being necessary when we created new wizards that remove the need to understand all these tricks. This adventure helped me realize that the wizard is the best API as mentioned in Chapter 9, Keep Testability In Mind. Thanks Rich for talking this wisdom out of me.

Rich also was the first external NetBeans developer who tried to contribute to our APIs via the APIReview process, as described in Chapter 16, Teamwork. After reading the chapter, Rich told me that he liked the secret behind the history of the APIReview process invention. Rich also asked whether I got some punishment for revealing the secret. Well, I did not, as nobody affected read the book yet, but I'll keep you posted. Thanks Rich for practising the APIReviews with us.

TomWheeler

Tom is long time NetBeans user, building applications on top of NetBeans Platform for Boeing. He knows NetBeans APIs well, as he is building upon them, however not only that, he is also an architect! He builds Boeing NetBeans Platform that is then consumed by millions of Boeing developers to create their desktop applications. In some sense, the next Boeing airplane is going to be build with NetBeans. Thanks Tom for making me feel more proud next time I use your airplanes.

I knew Tom as a very good speaker. I could not imagine someone who handles English so well, could be bad reviewer and indeed, I received just valuable comments by Tom. However I selected Tom for yet another reason: Just like me, he is architect working in a team. He needs to guide his team members, tell them how to design properly, verify that they understand. That is why I expected unique comments from Tom and I was not wrong. When Tom visited Prague last time, he told me: When I was reading through the book, I was always wondering how do I practice these design skills with my team, and then I came to Chapter 17, Using Games to Improve API Design Skills, and suddenly the answer was clear! When I assembled the book, I was not sure whether to include Chapter 17 or not, so thanks a lot Tom, for saying these words and confirming that my decision was right.

JesseGlick

Jesse joined the NetBeans project in 1998 to write technical documentation. As a result he was reading through the NetBeans APIs of that time, mostly created by me and documenting them (at that period of time we were not yet practising the use case driven API design as popularized by Chapter 3, Determining What Makes a Good API). As API is all about communication, his work was essential for the success of NetBeans project. Thanks Jesse, for doing that.

However, Jesse did not stop on the level of documenting my APIs, he also started to write his own. In fact he is architect of quite a big portion of NetBeans IDE. Jesse's adventures during the API design motivated many observations and conclusions present in TheAPIBook. Whenever we argued about APIs with each other or with other persons, I've taken notes, added a paragraph or two. Sometimes I even directly copied Jesse's email into the raw book's material. For example the Do Not Put Setters Where They Do Not Belong in Chapter 5, Do Not Expose More Than You Want is heavily based on one such email conversation.

Jesse speaks a special kind of English, at least from my point of view. It is always pleasure to read it. That is why I have always found it a sad that Jesse keeps all his notes in emails and does not publish them for everyone to see. That is why I am very happy about Jesse's decision to join the API Design blogosphere. Thanks Jesse for all your past and future notes.

Friends

Family

There is a reason why every book is dedicated to family. It is always harder to write it and it takes so much time, that the support and patience from all family members is more than needed. I wrote TheAPIBook in my spare time, after returning back from work and this indeed required a lot of understanding from my wife as she needed to spend more of her time to look over our children. Thanks a lot for that.

However not only my wife was affected by me spending a lot of time with TheAPIBook. By a chance, at the same time when I was finishing my work on the book, my wife needed to pass final exams at her university. As a result we needed a lot of help from the rest of the family as well. I'd like to namely thank to grandmother of my children for taking care of them and allowing me to finish TheAPIBook and my wife to finish the university. The book is officially dedicated to GeertjanWielenga and PatrickKeegan as without them it would never be translated to real English, however your name shall be on the thanks page as well, grandma.

Tim Boudreau

Tim deserves really big note in this thanks list, because, without him, I would never think about the possibility to write a book. I had my own notes and did a bunch of talks on the topic of API Design, however I never felt being capable of writing a book. It was Tim who once said: "Let's write a book describing how to write APIs that will stand the test of time." At that moment the journey of TheAPIBook started to materialize. Thanks for showing me that the book can become real, Tim.

At that time I still considered very likely that I will just co-author the book with Tim. However as Tim has always many things to do, we did not really proceeded anywhere and at the end I decided to publish the book by myself. Still, there is a lot of Tim's influence in the content of the book. Tim insisted on creating a methodology, which I described in the The_Future chapter. Tim also invented the term conceptual surface which is very good way to measure complexity of an API. At the end, Tim is not co-author of TheAPIBook, however he still remain one of the authors of many of the books ideas. Thanks Tim for contributing them.

Honzík Zahrádka

There can be a long way between knowing a journey and really taking it. Tim revealed me the possibility to write TheAPIBook, however I have not started to write it yet. I was waiting. I had my notes, but I was afraid to really undertake the journey and start to write, find a publisher, etc. This lasted till summer 2007, when, at one family garden party I met my wife's cousin, Honzík. I told him about the idea of writing a book and about my fear of really doing it. He said something like: "You know what to write about; you know it is an interesting topic; you know you are an expert in it. So... why haven't you started writing yet?". So cruel, but so true. At that time I decided that I need to write the first chapter, send it to publishers and if they do not refuse, really publish the book. I am glad that a year later, the book is available. Thanks Honzíku for pushing me forward at the right moment.