Tired of formatting and polishing the programmer's notes? Learn just enough Java to decode Java source files, and then you can start writing Java documentation.

You don't need to know everything. You just need to be able to decode some of the source code, extract some key information, and use your knowledge to convert that information into useful documentation.

In this workshop, you will learn just enough Java to get you decoding .java source files well enough to write useful documentation. We will show you how to use javadoc, Sun's documentaton generation program for Java.

We will also introduce Microsoft's new C# language (sometimes called .NET) and show you the key differences between documenting C# and documenting Java. You will do exercises where you document a real API from a real product.

After this workshop, you will be able to use your knowledge of Java to start writing documentation, instead of simply cutting, pasting, polishing and formatting the programmers' notes.

For full details, see What You Will Learn.

What else should I know?

To succeed with an API project, you also need to understand how to organize and produce SDK documentation, especially the how-to information that belongs in a Developer's Guide. You should understand why companies bother with SDKs, what programmers want and why sample programs are so important.

This information is not easy to find. It's not on the Web. It's not in any book on technical writing or Java programming. And it's certainly not in any book written for "Dummies" or "Complete Idiots"!

That's why Gordon & Gordon developed a 1-day workshop that covers all this material:
Documenting APIs and SDKs.

Uh-oh. My company's APIs are in another language.

Programmers may hotly debate the virtues and defects of different programming languages. Technical writers can be more relaxed: much of what we need to know to document APIs doesn't change very much if we switch from language to another.

If your API is written in C or C++ we recommend another of our 1-day workshops:
Just Enough C and C++

If your API is written in (or for) another programming language, please send us an e-mail with the specifics.

But I still don't understand what the programmers are talking about?!

To document an SDK, you need to go below the user interface of buttons and dialogs—often way, way below. You need to understand the many layers, components and platforms that underlie the software: clients, servers, .NET, mainframes, UNIX, Linux, PDAs, widgets, objects, classes, components, middle tiers—and yes, even daemons!

To meet this need, Gordon & Gordon developed a 1-day workshop that covers this important background: Understanding Complex Software

TO TOP

Who Should Attend

• Technical writers with a capital T
• Writers with some previous exposure to computer programming (in any programming language)
• Writers or programmers being asked to document SDKs written in Java
• In-house writers or consultants who want to break into the lucrative field of writing SDKs.

---

Learning Objectives

At the end of this workshop, you will be able to decode Java source files and make an educated guess about the purpose of each function. And you will be able to work with Java software developers to create useful documentation for a Software Development Kit (SDK).

---

What You Will Learn

A First Look at APIs

• What is an API?
• The difference between an API and an SDK
• Who is the user of an API?
• How javadoc tells you what you need to know
• Classes and objects, methods and properties
• Buzzword soup: methods, member functions, functions, properties
• The user interface of a Java method
• Documenting that user interface
• Determining a method's name, purpose, parameters and return value
• Our focus: converting source files to documentation

Just Enough Background

• Programming languages: there are many!
• Origin of C and C++ and their relationship to Java
• Origin of Java and how it affects documentation
• The Java 2 SDK
• Java Integrated Development Environments (IDEs)
• Applets and applications
• JavaBeans and Enterprise Java Beans
• Origins of C#, .NET and Web services
• Microsoft, Sun and the politics of programming languages

Just Enough Java Syntax

• Methods (functions): black boxes that do something very specific
• Types: numbers, characters, strings and other kinds of data
• Parameters: what goes into a function
• Return values: what comes out of a function
• Signatures: all an API user needs to know... mostly!
• Private and public: controlling access to methods and properties
• Bundling classes into packages
• Java interfaces: the how and why

A Little Bit of C#

• How Java and C# are very similar
• The differences between Java and C#
• How these differences affect documentation
• Documentation generation programs for the Microsoft universe

TO TOP

---

What People Say about this Workshop

Note: Just Enough Java is a new workshop, but much of the material is adapted from the 2-day version of Documenting APIs and SDKs, an earlier workshop that Manuel Gordon has presented several times.

Here is a selection of comments on the relevant parts of Documenting APIs and SDKs:

"I'm excited by the fact that I can now READ and UNDERSTAND the code I spend most of the time cutting and pasting!"

"We have so much trouble finding tech writers who can read source files and document APIs! This course will be really, really good for the other two writers on my team."

"Love the exercises. I find this course is bringing everything together that I've been trying to learn on my own so far."

"I feel able to analyze [source code] in an intelligent-enough way to produce skeletal documentation. A definite improvement!"

"Fortunately, I could always work from quite complete documentation written by programmers. I just had to reformulate, reformat, and update. I never had to dig in the source files. Now, I know how to work the other way around, in case I need to some day. Today's course was really educational."

"Good tips for extracting important information from code and other sources."

"I have no programming background. Part of my job is to format the docs written by programmers. After this training, I am going to be able to write the doc by myself."

"I wanted to stop guessing and get informed! Now I am much better prepared to do this work, and have a clue where to get supporting information."

"Manny is a lively, very interesting instructor."

"Overall, the course was EXCELLENT. I have benefitted ENORMOUSLY and it will help me TREMENDOUSLY in my work. I think it has been one of the most useful courses I have taken. Thank you so very much."

TO TOP

---

Upcoming Presentations

This workshop is not currently scheduled.

To be notified when this workshop is next held, email us at manuel@gordonandgordon.com.

TO TOP

---

How to Contact Us