Moderator (MDR): MDR-gvoss
Guest Speaker (SPK): SPK-name
MDR-gvoss: Hello, everyone. Welcome to the Java Developer
Connection Discussion Forum. This week we'll be talking with the Mary Campione
and Kathy Walrath, authors of `The Java Tutorial,' the official JavaSoft
introduction to the world of Java programming. The book is part of the `Java
Series' of books published by Addison Wesley. Mary Campione is a technical
writer at JavaSoft. She specializes in writing programmers documentation for
new and emerging software technologies. Among other books Mary has written,
she co-authored 'Postscript by Example,' which received a five-star rating
from PC Report. Kathy Walrath is a technical writer at JavaSoft as well. Kathy
specializes in how-to guides for programmers. Prior to writing about Java at
both Sun and JavaSoft, Kathy wrote extensively about Unix, Mac, and NextStep.
Both Mary and Kathy are (relatively) recent and proud mothers. Mary's baby
Sophia is nine month's old and has developed a fondness for holding beer
bottles, much to her mother's distress. Kathy's son, Cosmo is two weeks younger
than Sophia (He's not named after Kramer, dammit! says Kathy). She also has a
daughter, Laine, who is two and a half. Welcome to both of you!
SPK-mem: Good morning!
SPK-Kathy: Hello!
MDR-gvoss: One of the interesting aspects of this book is that
is is simultaneously available both as a traditional bound book, and as an
electronic Web document through JavaSoft's primary web site. It's hard to
estimate how many people have read the tutorial, though it's safe to say that
more people have been introduced to Java through Mary and Kathy's book than any
other single source. It's quite an accomplishment to have tackled a project as
large as this. How long did it take you to write the book?
SPK-Kathy: It's hard to say. Mary started work on it in
February of 1995, but I'd already written a (very) little applet-writing guide
before that. And then we took some baby time off. I guess we can say that the
book took 2 years (although we had no idea it'd be a book for the first year we
worked on the tutorial).
MDR-gvoss: So you've been involved with Java for some time,
Kathy. Can you talk a little bit about what it was like in the early
days--particularly about how the book project came about, and how it evolved.
SPK-Kathy: Well, I joined FirstPerson (as it was called) to
write task-oriented programmer documentation, but they needed me to work on the
Oak spec first (Java used to be called Oak). A year later I finally was able to
really concentrate on the task-oriented doc. And that became the tutorial.
MDR-gvoss: Mary is composing an answer to the same question.
If any of you have questions you'd like to ask Mary and Kathy, now is a good
time to send them.
SPK-mem: When I joined in Feb of 95, we took Kathy's online
programmer's guide for writing applets. and made it into one of the
"trails" that now make up the tutorial. The concept was that we could
add lessons and trails as we finished them. This modularity allowed us to
provide information to our users/readers before it ever would have been
available in printed format.
uomini: My wife and I have a two-year-old, Jonathan,
who is a handfull, but lots of fun. His first word, as I recall, was `grep' (or
something like that), and he loves to pound away at the keyboard .
Unfortunately, in spite of a promising Unix beginning, he seems to prefer the
Mac...
MDR-gvoss: Looks like we have other fans of young children in
the audience. We could have a forum sometime about the trials and tribulations
of writing software, documentation, and raising young children at the same
time. Often, the first order of the day, upon arriving at work, is to share
fascinating baby experiences from the night before.
SPK-Kathy: Fascinating for us, but not for people with weak
stomachs...
MDR-gvoss: You've probably heard just about every question
under the sun. That must really help you refine the tutorial in terms of
addressing common questions and common misunderstandings. What is the most
difficult thing about teaching someone to program in Java?
SPK-mem: In writing the tutorial we found that our readers
came from many different backgrounds and experience levels (especially after we
got the JDK onto the PC and Macintosh). We had complete beginner programmers,
programmers who didn't have object-oriented experience, and programmers who
knew OO technology but not Java. It was difficult to find the right balance for
all of these people.
SPK-Kathy: For many people, getting started seems to be the
hardest part. Just getting to the point where they can run a program is a
struggle. We try to address that with the Getting Started trail.
MDR-gvoss: How do you adress all the different backgrounds
(Mac, Unix, Windows) and experience levels (beginner, intermediate, advanced)?
It must be pretty tough.
SPK-mem: We limit ourselves to documenting the JDK as it's
shipped by JavaSoft. We don't document all of the other tools shipped by our
third party vendors. In terms of the reader's level of experience, we try to
provide information at all levels and just make it clear who the information is
for.
SPK-Kathy: The hypertext format also helps intermediate and
advanced people to easily skip information that they don't need. And it helps
the beginners know that they can get more information somewhere else.
MDR-gvoss: Do you write all your own code?
SPK-mem: For the most part I write all of my own examples. On
occasion I have used examples from some of the engineers around here. (Dave
Connelly's example in the I/O section.) I give credit to the engineers when I
use their code.
SPK-Kathy: Me too. I've especially used Jim Graham's code for
some of the more difficult image processing.
MDR-gvoss: How do you decide what kinds of programs to write?
Are there some guidelines you set for yourself? For example, is there some
sort of criteria you follow when trying to design an example program that best
illustrates some point or concept you are trying to get across?
SPK-Kathy: We generally try to write the smallest program
possible that illustrates the concept we're trying to get across. We also try
to make the program interesting, if we have the time. Sometimes our programs
don't do as much error checking or GUI formatting as production code would.
It's a tradeoff between readability and "good practice."
paradigm: Any idea when we'll see tutorial info on
Beans?
SPK-mem: Greg Voss (our host for the day) wrote a beans
tutorial for the Java Developer Connection site. We've incorporated it into the
online tutorial...In fact, I just posted it to the website yesterday. Check it
out: http://java.sun.com/nav/read/Tutorial/beans/index.html BTW: He's
still working on it...so keep checking for new material. Greg, how's progress?
MDR-gvoss: Thanks for putting the pressure on :) I've been
trying to get to the the advanced section of the tutorial for the past month
now,--but there are always so many things to do, like hosting JDC Forums. I'll
fall back on my usual answer: the draft is in the mail. Seriously, I hope to
get the advanced section done over the next two to three weeks.
spietrowicz: Congrats on the kids and getting the
book done! Addison Wesley has a number of Java books out already, and a few
more on the way. Are either of you (or both) considering writing another book?
SPK-mem: Thanks for the kudos. Actually, the kids were a big
incentive for us to complete the book on time. Our due dates were 3 weeks
apart and coincidental with getting the manuscript to Addison-Wesley. We were
quite a sight....8 months pregnant and working til midnight....now Kathy will
reply about the serious stuff...more books.
SPK-Kathy: We're working on a JDKTM 1.1 version of the
tutorial. It'll still have the 1.0.2 stuff, but it'll point out where things
have changed in the 1.1 world, and it'll have information on how to implement
those 1.1 equivalents. It'll also have conversion information. We're also
hoping to put out a second volume of the tutorial that will cover completely
new 1.1 features such as beans and internationalization.
MDR-gvoss: A lot of comments about kids today. I think we
~should~ have a special forum. How did you go about doing the research required
to write the book? This must have involved a lot of interviews. How did you
come up with the basic organizational structure and list of topics?
SPK-mem: I try to write examples for everything. In the course of developing the examples, I run into real problems and have to solve them. The result is a tutorial that documents the process. When I'd get confused with something, I'd go to the engineer with a list of specific questions. The engineers seem to like this approach because it doesn't waste their time and they don't spend time "lecturing." The organization of the tutorial developed over time and was partially a result of our desire to publish small pieces of it at a time. By breaking the tutorial into trails and lessons, it became fairly modular and was easier to maintain and develop.
MDR-gvoss: Yes, I very much like the breakup of the tutorial
into trails and lessons. It's a nice metaphor. Very friendly. Have you gotten
a lot of positive feedback about this structure?
SPK-mem: Well, I like to snowboard. So, it's a way for me to
dream about the slopes while I'm working. I'd say most people are positive
about the structure. A few people have indicated that they don't like it. I
think that they expect a more linear approach, like a traditional teaching
text, but the hierarchical structure is more appropriate for online learning.
MDR-gvoss: At what point did the online version of the
tutorial turn into a book to be published in print format? What kinds of
problems were involved in moving from an electronic web format to a printed
and bound book? I imagine Addision Wesley had some specific formatting
requirements that forced you to modify a lot of the organization.
SPK-Kathy: We don't remember when we decided to make it a
book! It happened around the time when we (the people currently known as
JavaSoft) decided to publish The Java Series. The tutorial had existed online
for quite a while before it turned into a book. Since we wanted to keep the
tutorial online and free, we sort of had to keep the book in a similar
hypertext format (or else it never would have come out). Even so, the
conversion from HTML (actually, mem4) to Frame files was pretty tedious (even
with automated help).
SPK-mem: Once we converted it to a book, we found that the
reviewers were confused by the hierarchical structure and we had to
"flatten" some of the introductions.
MDR-gvoss: When writing the beans tutorial, I came to
appreciate, a text preprocessor developed by Mary called mem4. It automatically
handles all the linkage sequences for navigating through the online version of
the book. (By the way, mem4 is a cute little pun, appreciated best by Unix
language processing techies who may be familiar with the macro preprocessor
called m4. m4 was the original model that inspired the preprocessor used in C.
Mary's login id is 'mem' so it seemed natural to call a language she invented
mem4.) What got you thinking along the lines of writing the mem4 preprocessor.
You write the original version in Java, right?
SPK-mem: We were changing our page format on a pretty regular
basis and I got sick of modifying every file every time we came up with a new
design for the header and footer and the inline links. (And I think that Kathy
was about ready to inflict harm on me everytime I made her modify all her files
for a new page format.) I tried to use m4 but I needed some special features so
I ended up writing my own. I originally wrote it in Java but Perl ended up
being a better choice because it's faster at text manipulation. So now it's a
Perl script.
MDR-gvoss: Is this true, Kathy? You wouldn't really have hurt
her would you? :)
spietrowicz: There are a LOT of Java books out there
already, and many more coming. Are you surprised at the number of Java books
that are out now, or did you expect that when you decided to do your own book?
SPK-Kathy: Considering how Java has taken off, I'm not
surprised at the number of books. However, I'm always amazed at how Java's
taken off. Especially after working at NeXT and seeing that superior
technology doesn't always win (at the time, anyway).
SPK-mem: When we were developing the online version there
were no books out. We were responding to users demands to get information out
there as quickly as we could. When we finally got the manuscript to
Addison-Wesley, there were probably 5 books out there. By the time it hit the
bookstores there were 30 or 40. It really took off... and very quickly.
MDR-gvoss: Back to mem4, for a second. Are you basically
happy with the result. Given today's HTML editing tools, would you still build
something like mem4 if you were starting fresh today? What advice would you
give to someone considering writing language processing tools, like mem4, who
may be publishing a book, or regularing posting articles to web sites
containing a lot of documents?
SPK-mem: Personally, I would love something that was easier to
work with. Humans shouldn't have to code in HTML (remember that everything but
the common page elements are in HTML). Advice....get someone else to provide
you with the tools and concentrate on writing the book.
MDR-gvoss: Kathy, you had some URLs for useful documents,
especially those relevant to JDK 1.1, and to new AWT information. Did you want
to go ahead and post those now.
SPK-Kathy: Yes, I wanted to give you all a few URLs to help
you use the AWT and convert your programs to the 1.1 API (if and when you
choose to do that): The AWT Home Page:
http://www.javasoft.com/products/jdk/awt/ **THE place to find out about the
latest AWT news.** "How to Convert Programs to the 1.1 AWT API"
http://www.javasoft.com/products/jdk/1.1/
docs/guide/awt/HowToUpgrade.html
**the master document for converting GUI-using programs** "Deprecated
Methods in the 1.1 AWT"
http://www.javasoft.com/products/jdk/1.1/
docs/guide/awt/DeprecatedMethods.html
**has a handy conversion table to help you get rid of those deprecation
warnings** "Providing Both 1.0.2 and 1.1 Programs"
http://www.javasoft.com/products/jdk/1.1/
docs/guide/awt/providingboth/ **CHECK
THIS OUT AND LET ME KNOW WHETHER THE HACK (excuse me, "second
technique") WORKS FOR YOU!** And, of course, "The Java
Tutorial" http://www.javasoft.com/Series/Tutorial
MDR-gvoss: Last question: One of the approaches to publishing
now possible, because of the web, is what I've heard you call a `living
document,' Mary. This let's you post the complete structure for a given
chapter that may not be complete. You may have written half or three quarters
of the material, but you can leave stub pages with a message indicating that
content will eventually be fleshed out. This opens up all kinds of interesting
possibilities (and problems) for updating and revising material more
frequently. Can you talk about this a little. What kind of feedback do you get
when you attach `Pending' tags to the table of contents of a chapter under
development. Are the readers resentful? Or are they glad because they are
getting the material earlier than would be possible through traditional
publishing channels?
SPK-mem: As long as it's clearly marked as pending, people
don't seem to mind. I think that people like to see progress and that they
look forward to checking in to see what new material we have. We can inform
our readers without much effort that we are working on certain areas. In
fact, at first we just left broken links in place. People hated that. As soon
as we marked things as pending they quieted down. So far, we haven't received
any complaints about our [PENDING]s.
MDR-gvoss: I've enjoyed talking to both of you, Mary and
Kathy. Hope you'll come back and talk to us when you've got some new material
to post. Thanks for talking with us.
SPK-mem: It was fun. Bye!
SPK-Kathy: You're very welcome. Bye!
MDR-gvoss: Thanks to everyone else for joining us. Look
forward to the posted transcript on the JDC website later this week. See
you next time. Last moderator signing off. The forum is now unmoderated
