Updated:
Feb-29-2008

Documenting SDKs
Wednesday, Mar-26 (All Day)

Presenter: Manuel Gordon, Gordon and Gordon
Location: (141 W. 38th St., New York City)

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.

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

Cost

  • $200 - STC members
  • $240 - Non-members

Top of Page