JaroslavTulach at 07:16, 28 May 2010 - 2010-05-28 07:16:53

←Older revision Revision as of 07:16, 28 May 2010
Line 13: Line 13:
Originally, according to the deal with my publisher, both Patrick and Geertjan were supposed to be ''translators'' only. They were supposed to convert my [[wikipedia::Basic_english|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!''
Originally, according to the deal with my publisher, both Patrick and Geertjan were supposed to be ''translators'' only. They were supposed to convert my [[wikipedia::Basic_english|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!''
-
== [[wikipedia::Apress|Apress]] ==
+
== [[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 [[wikipedia::Apress|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.
+
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 Andres ===
-
Clay was my first [[wikipedia::Apress|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]]:
+
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."
''"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."
Line 28: Line 28:
=== Kylie Johnston ===
=== Kylie Johnston ===
-
As soon as Clay was satisfied with the text, he passed me to hands of [[wikipedia::Apress|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.
+
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 Davidson Pfalzer ===

213.220.235.54: /* Geertjan and Patrick */ - 2008-08-13 21:24:46

Geertjan and Patrick

←Older revision Revision as of 21:24, 13 August 2008
Line 9: Line 9:
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.
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.
-
[[PatrickKeegan|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 [[wikipedia::Hrabal|Hrabal]]'s books, where the words flow like a river and as soon as you start, 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. [[PatrickKeegan|Patrick]] provided them and I am really thankful to him for doing that.
+
[[PatrickKeegan|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 [[wikipedia::Hrabal|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. [[PatrickKeegan|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 [[wikipedia::Basic_english|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!''
Originally, according to the deal with my publisher, both Patrick and Geertjan were supposed to be ''translators'' only. They were supposed to convert my [[wikipedia::Basic_english|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!''

JaroslavTulach: /* Support Units */ - 2008-07-27 18:57:06

Support Units

←Older revision Revision as of 18:57, 27 July 2008
Line 42: Line 42:
{{:ThanksReviewers}}
{{:ThanksReviewers}}
-
== [[ThanksFriends|Support Units]] ==
+
== [[ThanksFriends|Friends]] ==
-
* family for patience
+
{{:ThanksFriends}}
-
* Honzík for telling me to write the book
+
-
* Tim and his cons and pros
+

JaroslavTulach at 17:39, 27 July 2008 - 2008-07-27 17:39:37

←Older revision Revision as of 17:39, 27 July 2008
Line 42: Line 42:
{{:ThanksReviewers}}
{{:ThanksReviewers}}
-
== Support Units ==
+
== [[ThanksFriends|Support Units]] ==
* family for patience
* family for patience
* Honzík for telling me to write the book
* Honzík for telling me to write the book
* Tim and his cons and pros
* Tim and his cons and pros

JaroslavTulach: /* Ellie Fountain */ - 2008-07-09 21:06:30

Ellie Fountain

←Older revision Revision as of 21:06, 9 July 2008
Line 40: Line 40:
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 [[wikipedia::ISO-8859-2|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.
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 [[wikipedia::ISO-8859-2|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.
-
[[ThanksReviewers]]
+
{{:ThanksReviewers}}
== Support Units ==
== Support Units ==

JaroslavTulach at 20:58, 9 July 2008 - 2008-07-09 20:58:09

←Older revision Revision as of 20:58, 9 July 2008
Line 40: Line 40:
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 [[wikipedia::ISO-8859-2|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.
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 [[wikipedia::ISO-8859-2|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]] ==
+
[[ThanksReviewers]]
-
 
+
-
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 [[InvitationForReviewers|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 now, 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 [[http://www.mff.cuni.cz/toUTF8.en/ Faculty of Mathematics and Physics]] at [[http://www.cuni.cz Charles University]] in [[wikipedia::Prague|Prague]]. We needed to finish a compulsory student project and decided to create a [[wikipedia::Borland_Delphi|Delphi]] for [[wikipedia::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 such project. Luckily, we knew Adam, a visiting professor not knowing exactly what it takes to lead seven students and their project. 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.
+
-
 
+
-
TBD: lost for a while, external to current netbeans, user, new to API design
+
-
 
+
-
=== [[DaveKoelle]] ===
+
-
 
+
-
TBD: API design guru, http://www.jfugue.org
+
-
 
+
-
=== [[MartinRinard]] ===
+
-
 
+
-
TBD: invented term [[Cluelessness]]
+
-
 
+
-
=== [[User:RichUnger|Rich Unger]] ===
+
-
 
+
-
TBD: long time user, visitor
+
-
 
+
-
=== [[TomWheeler]] ===
+
-
 
+
-
TBD:
+
-
 
+
-
=== [[JesseGlick]] ===
+
-
 
+
-
TBD:
+
== Support Units ==
== Support Units ==

JaroslavTulach: /* AdamDingle */ - 2008-07-08 19:28:21

AdamDingle

←Older revision Revision as of 19:28, 8 July 2008
Line 52: Line 52:
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!
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]] ==
+
=== [[AdamDingle]] ===
 +
As you may know the roots of NetBeans can be traced to 1995, when seven of us, students of [[http://www.mff.cuni.cz/toUTF8.en/ Faculty of Mathematics and Physics]] at [[http://www.cuni.cz Charles University]] in [[wikipedia::Prague|Prague]]. We needed to finish a compulsory student project and decided to create a [[wikipedia::Borland_Delphi|Delphi]] for [[wikipedia::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 such project. Luckily, we knew Adam, a visiting professor not knowing exactly what it takes to lead seven students and their project. 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.
-
* [[DaveKoelle]] <!-- dmkoelle@gmail.com, http://www.jfugue.org -->
+
TBD: lost for a while, external to current netbeans, user, new to API design
-
* [[MartinRinard]] <!-- invented term '''Cluelessness''' -->
+
 
-
* [[User:RichUnger|Rich Unger]]
+
=== [[DaveKoelle]] ===
-
* [[TomWheeler]]
+
 
-
* [[JesseGlick]]
+
TBD: API design guru, http://www.jfugue.org
 +
 
 +
=== [[MartinRinard]] ===
 +
 
 +
TBD: invented term [[Cluelessness]]
 +
 
 +
=== [[User:RichUnger|Rich Unger]] ===
 +
 
 +
TBD: long time user, visitor
 +
 
 +
=== [[TomWheeler]] ===
 +
 
 +
TBD:
 +
 
 +
=== [[JesseGlick]] ===
 +
 
 +
TBD:
 +
 
 +
== Support Units ==
* family for patience
* family for patience
* Honzík for telling me to write the book
* Honzík for telling me to write the book
* Tim and his cons and pros
* Tim and his cons and pros

JaroslavTulach: /* Reviewers */ - 2008-07-08 19:03:38

Reviewers

←Older revision Revision as of 19:03, 8 July 2008
Line 42: Line 42:
== [[Reviewers]] ==
== [[Reviewers]] ==
-
After sending the [[InvitationForReviewers]], these guys generously accepted to take a look at the book. Thank you all.
+
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 [[InvitationForReviewers|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 now, 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]] ==
 +
 
-
* [[AndreiBadea]]
 
-
* [[AdamDingle]]
 
* [[DaveKoelle]] <!-- dmkoelle@gmail.com, http://www.jfugue.org -->
* [[DaveKoelle]] <!-- dmkoelle@gmail.com, http://www.jfugue.org -->
* [[MartinRinard]] <!-- invented term '''Cluelessness''' -->
* [[MartinRinard]] <!-- invented term '''Cluelessness''' -->

192.9.112.196: /* Susannah Davidson Pfalzer */ - 2008-06-23 11:45:34

Susannah Davidson Pfalzer

←Older revision Revision as of 11:45, 23 June 2008
Line 34: Line 34:
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).
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 speaker's 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.
+
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 Fountain ===

192.9.112.196: /* Susannah Davidson Pfalzer */ - 2008-06-23 11:44:36

Susannah Davidson Pfalzer

←Older revision Revision as of 11:44, 23 June 2008
Line 32: Line 32:
=== Susannah Davidson Pfalzer ===
=== Susannah Davidson Pfalzer ===
-
Susannah was continuing in the work started by [[GeertjanWielenga]] and [[PatrickKeegan]]. She polish 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).
+
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 speaker's 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.
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 speaker's 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.