Gordon & Gordon is a partnership of two award-winning writers who specialize in technology, Gordon Graham and Manuel Gordon. Our clients hire us to explain complex products and to persuade demanding customers. And we share our many years of experience through practical, cost-effective consulting and training.
Documenting APIs and SDKs
|
This entire workshop now available on DVD.
Gain from the rich interaction of the live workshop, with none of the cost and headaches of getting there!
Workshop Overview
"Help wanted: Technical Writer to document SDKs. Must have Bachelor's degree in Computer Science, Master's degree in Technical Communication, plus five year's experience in a similar position..."
In their dreams! In the real world, there are a lot more SDKs that need documenting than technical writers with the ideal qualifications.
Documenting SDKs isn't easy, and it's not for everyone. But it is a highly sought skill.
It's work that will earn you respect, both from other writers and from programmers. And it's one of the best-paying gigs in our industry.Sure, it's a tough job, but somebody's got to do it. Why not you?
Er, what's an API?
An Application Programming Interface (API) is the interface that software presents to programmers who need to build applications on top of that software. If you can package that API with useful documentation and good sample programs, you have a Software Development Kit (SDK) your company can sell.
No documentation, no SDK!
Programmers and marketing people often use the terms "API" and "SDK" interchangeably.
What will this workshop give me?
This 1-day workshop focuses on how to organize and produce SDK documentation, no matter what programming language the API is written in.
You'll learn why companies bother with SDKs, what programmers want and why sample programs are so important.For full details, see What You Will Learn.
Do I need to be a programmer?
To document an SDK, you should learn something about the programming language it was written in... usually C, C++ or Java.
Yes, there are lots of thick books and lengthy courses that will teach you how to program in those languages.
But that's overkill for a tech writer with an urgent deadline.
So Gordon & Gordon developed two 1-day workshops that cover exactly what you need to know about each language:
But I still don't understand what the programmers are talking about?!
To document an SDK, you often need to understand the many layers, components and platforms that underlie the software: clients, servers, mainframes, UNIX, Linux, PDAs, widgets, objects, classes, components, middle tiers—and yes, even daemons!
And since you may well be working closely with programmers, it helps to understand the issues and tradeoffs that drive all software design, including the design of APIs.
To meet this need, Gordon & Gordon developed a 1-day workshop that covers all this background:
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
- 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 work with software developers to create useful documentation for a Software Development Kit (SDK).
What You Will Learn
Why Bother with SDKs?
- Why software vendors sell SDKs
- Why customers buy SDKs
- How programmers use SDKs
What SDK Documentation Looks Like
- The Reference Manual
- The Developer's Guide
- Other forms of online and embedded documentation
What Programmers Really Want in an SDK
- Code, code and more code
- The differences between code snippets, sample programs and full-fledged demo programs
- How to specify code samples that are useful to your readers
- How to embed sample code in documentation
Generating Reference Documentation
- Embedding documentation in code
- The benefits of generating (vs. writing) reference documentation
- How Javadoc, doxygen, Document X and similar tools work
The Outline for a Developer's Guide
- Introduction, Installation, Getting Started, Task 1, Task 2... Appendices
- Applying the Universal Tasks
- Determining the tasks that API users (programmers) actually perform
- Avoiding the great big ugly Theory chapter
- What goes into the Installation chapter
- Building chapters around sample programs
Documentation Strategies
- Applying USE (Understand, Simplify, Explain) to SDKs
- "User Manual as Spec"
- Building SDK documentation teams that include programmers
- Typical documentation plan for an SDK
- When to bring in a consultant
- Getting access to code and developers' tools
- Educating yourself further
What People Say About this Workshop
"I think this course is just amazing for tech writers new to API writing!"
"All the information was fabulous... Covered a lot of ground."
"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."
"I got great info, feedback, affirmation, motivation, direction to go back and get the right job done."
"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."
"Excellent introduction to the raison d'etre of APIs and SDKs.
The course builds a writer's confidence that they are on the right track to developing acceptable SDK documentation."
"Solid, basic API concepts made concrete through examples. Great presentation manner and sense of humour, depth of knowledge and experience."
"Manny is a lively, very interesting instructor."
"Lots of information, entertaining."
"The pace is good, the content is rich. You have captured my interest and excited my learning curve."
"Manny is a very good and interesting animator."
"Even though I know some of these concepts, having them presented in a global view is interesting and refreshing."
"A very good introduction to what it's all about."
"I certainly found the course useful. It has catapulted the dialogue on what goes into our SDK up to management level."
Upcoming Presentations
This workshop will be presented in Montreal on April 20, 2005. Click here for details.
To be notified when this workshop is next held, email us at manuel@gordonandgordon.com.
How to Contact Us
|
How to reach Tel: (514) 934-3274
|
|
How to reach Tel: (705) 842-2428 |
