Upcoming webinar: Creating code samples for API/SDK documentation
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
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: https://www.youtube.com/watch?v=sumQULczJOg. When the webinar is over, a replay will be available on the same youtube page.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.