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
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: http://www.youtube.com/watch?v=sumQULczJOg. When the webinar is over, a replay will be available on the same youtube page.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.
About Tom Johnson
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in simplifying complexity, API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.