Tired of formatting and polishing the programmer's notes? Learn just enough C and C++ to decode header files, and then you can start writing 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 we present just enough C and C++ to get you decoding the header files used in every API written in those languages. You will see and work with real-world APIs for real products. After this workshop, you will be able to use your understanding of those header files to start writing documentation—instead of simply cutting, pasting 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 C/C++ 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 one language to another.

If your API is written in Java or C# (sometimes called .NET), we recommend another of our 1-day workshops:
Just Enough Java

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 C or C++
• 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 C or C++ header files and make an educated guess about the purpose of each function. And you will be able to work with C or C++ 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?
• The user interface of a C or C++ function
• Documenting that user interface
• Why the the header file is all you need to know
• Determining a function's name, purpose, parameters and return value
• Our focus: converting header files to documentation

Just Enough Background

• Programming languages: there are many!
• Origin of C and how it affects documentation
• Origin of C++ and how it affects documentation

Just Enough C Syntax

• 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!
• Structures: collections of data
• Pointers to data
• Pointers to pointers
• Enumerated types and other special types
• Decoding and documenting C header files

Just Enough C++ Syntax

• Nothing in C is alien to C++
• Classes that combine properties (data) and methods (functions)
• The relationship between objects and classes
• Constructors and destructors
• Inheritance, polymorphism and all that good object-oriented stuff
• Decoding and documenting C++ header files

Bonus Topics
These bonus topics are included in the workbook but will be covered only if time permits.

• Documenting components:
  COM, CORBA, DCOM, ActiveX... but mostly IPL
• Generating reference documentation with doxygen and other tools

TO TOP

---

What People Say about this Workshop

Note: Just Enough C or C++ 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 header 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 header files 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 header 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 will be presented in Montreal on April 27, 2005. Click here for details.

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

TO TOP

---

How to Contact Us