Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,505

Stitcher radio

follow us in feedly

Want more tech comm blogs to follow? See my Tech Comm Collection of Blogs on Feedly.

Adobe Robohelp

Upcoming webinar: Creating code samples for API/SDK documentation

May 9, 2014 • api-doc

May 30 update: Here's the recording of the presentation.

I'm giving a webinar on May 29 on the topic of creating code samples. The webinar is sponsored by the soap conference, which is a new conference in Poland that I featured on my blog a few weeks ago. Here are the details of the webinar:

Creating code samples for API/SDK documentation

soap webinar
Date: May 29, 2014
Time: 8am PST
Cost: Free
Location: Online (details below)

One challenging yet rewarding aspect of API/SDK documentation is creating code samples. Code samples show how to use an API or SDK in a real scenario, making calls, bringing back information, visualizing data, etc., and doing it in a specific programming language, such as JavaScript, PHP, Java, or some other language.

To create code samples, you don't need to be a full-fledged programmer, and many times you may not even create the samples yourself. Code samples tend to be simple illustrations of a particular technique or method, especially at it relates to your company's API or SDK.

When you create code samples, you format the code in a readable way, include comments, precede or follow the code with detailed explanations, and often visualize the results of the code.

In this webinar, you will learn the following:

  • How to learn programming concepts well enough to write code samples
  • What separates good code samples from bad code samples
  • Best practices for adding comments in code
  • How to create or gather code samples from engineers
  • How to integrate code samples alongside other API or SDK information
  • How to avoid various pitfalls in writing code
  • How to review code with engineers
  • How to contextualize code samples with real-world scenarios
  • How to integrate syntax highlighting with code samples
  • Although code samples may seem intimidating to writers unfamiliar with programming, diving into this field opens up a new landscape of learning, language, and capability. Documenting code and writing for developers presents technical writers with the ultimate challenge for simplifying complexity.

As you attempt to explain complicated code, you leverage many of the tools for simplifying complexity that you already know: using examples, communicating visually, avoiding jargon in favor of plain speech, formatting in a readable way, and more.

Developers are often blindsighted by their own expertise in the subject and fail to see gaps where users new to an API or SDK might stumble. As such, the technical writer with some programming knowledge fills a perfect gap for seeing the material with fresh perspective. With some effort, technical writers can provide useful descriptions of how code works and what users need to know.

For more information, see the creating code samples webinar description on the soap conference site.

Attending the webinar

The webinar will be through Google Hangouts. At the time of the webinar, just go to this link and press Play. If you have a Google+ account, you will be able to use the Q&A tool to ask questions.

You can also watch the webinar here: When the webinar is over, a replay will be available on the same youtube page.

follow us in feedly

Get new posts delivered straight to your inbox.

Subscriber count: 3,505

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.