writing code samples for api/sdk documentation
DESCRIPTION
This presentation is intended for technical writers creating documentation for APIs, SDKs, and other developer material.TRANSCRIPT
![Page 1: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/1.jpg)
How do you write code samples? 20
questions
soap! webinar. May 29, 2014
Tom Johnson @tomjohnson idratherbewriting.com [email protected]
![Page 2: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/2.jpg)
About me
Started doing API/SDK documentation a little more than a year ago at a Silicon Valley startup
Am still learning a ton, but enjoy this type of documentation a lot.
English major, writing background
First time presenting on this topic
Question format
![Page 3: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/3.jpg)
1. What are code samples?
Usually supplementary material that accompanies API or SDK reference documentation (particularly SDK).
Can be short or lengthy, full of comments and explanation or without any explanation at all.
Great example on jquery's documentation here: http://api.jquery.com/each/
Another good example: http://docs.oracle.com/javase/tutorial/java/javaOO/classes.html
![Page 4: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/4.jpg)
![Page 5: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/5.jpg)
![Page 6: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/6.jpg)
Head First Java, 2nd Edition
![Page 7: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/7.jpg)
2. Why add code samples?
Code samples are in another language. If audience speaks the language, the code communicates more clearly.
Examples are much more efficient than trying to describe syntax and methods in a narrative way.
Programmers often skip right to the examples to see how something is to be done.
Examples illustrate how your product works in an immediate and clear way.
![Page 8: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/8.jpg)
3. Which language should the code samples be in?
"I would say at least half of web APIs do not have sample code available because once you provide it in one language, developers will want sample code in Java, C#, Ruby, Python, Objective-C, PHP, etc. which is often not practical to provide. (The beauty of web APIs is that they can be called from almost any language; this is also a huge problem when it comes to sample code.) Instead of sample code, web API documentation often just shows sample requests and responses." – Peter Gruenbaum, SDK Bridge, Linkedin thread.
![Page 9: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/9.jpg)
4. Do I need to be a programmer to write code
samples?"… a writer must know enough programming to both read (and understand) code samples AND create their own code samples for the documentation. As others have mentioned, that doesn't require being a full-fledged programmer, but you need some solid programming knowledge. It is just like any other documentation project in my mind -- when I document software products, I use the product as an end user would to ensure that I understand what they need to know. For an API, if I'm writing the doc myself (as opposed to editing doc someone else wrote), I want to use the API as a developer would, for the same reason." -- Sara Schertz, Tech Writer / Bus. Analyst, Linkedin thread
![Page 10: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/10.jpg)
5. If I could write code, wouldn't I be a
developer?"We don’t need to be code ninjas. The code in an illustrative sample is not the same thing as the production-ready code in an application. … A code sample is a piece of syntactically correct and semantically useful code, written to illustrate the functionality and usage of an API or a developer tool. The code sample provides a stepping stone between the conceptual overviews in the developer’s guide, and the complex implementation required for a production-ready application." – Sarah Maddox, API technical writer at Google
![Page 11: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/11.jpg)
6. How do you know what's obvious without a
dev bckgrnd?flickr
![Page 12: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/12.jpg)
7. Can I just get all code samples from
engineers?
flickr
![Page 13: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/13.jpg)
8. How can I learn programming?
safariflow.com
safaribooksonline.com
lynda.com
teamtreehouse.com
codeschool.com
udemy.com
![Page 14: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/14.jpg)
9. How can I keep my brain from exploding?
![Page 15: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/15.jpg)
10. Are code samples hard to write?
![Page 16: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/16.jpg)
11. How do I add comments in code?
Head First Java, 2nd Edition
![Page 17: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/17.jpg)
Head First Java, 2nd Edition
![Page 18: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/18.jpg)
![Page 19: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/19.jpg)
12. How do I provide instructions for lengthy
samples? Build it up as a story
Or describe it section by section after providingthe full code.
![Page 20: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/20.jpg)
13. How do you explain code that is non-linear?
![Page 21: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/21.jpg)
14. Shouldn't I show our product's full
capabilities?
flickr
![Page 22: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/22.jpg)
15. Where do you put code samples?
Option 1: Separate from the reference material? Keeps reference material clean and minimal, but not as integrated.
Option 2: Integrated within each method or class? Makes sense from an organizational point of view, but makes doc bulky.
Option 3: Brief examples in reference material, with lengthier examples in a separate area.
![Page 23: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/23.jpg)
16. Can I adopt a playful, irreverent tone
with dev doc?"Code can always be a little more stressful than we would like, so don't be afraid to inject some humor into your comments. As far as brightening up someone's day when they're eyeballs deep in code, it doesn't get much better than reading a funny comment someone left. I've even caught myself laughing at comments I've written in the past. It's always a nice surprise and lightens the mood."
-- Chapter 9, Code Design, Learning JavaScript, by Tim Wright.
![Page 24: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/24.jpg)
17. What's the best way to review code
with engineers?flickr
![Page 25: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/25.jpg)
18. If I can get code to run myself, why review
it? Performance
Memory
Inefficiency
Best practices
![Page 26: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/26.jpg)
19. How can I make my code samples
readable?
![Page 27: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/27.jpg)
20. How do I avoid tedious updates with
new releases?
![Page 28: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/28.jpg)
The end
![Page 29: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/29.jpg)
References/AttributionsThe following are references to images and quotes used in this presentation. The numbers (e.g., "Question 4") correspond to the numbers on the slide titles, not necessarily the slide position in the slidedeck.
Question 1. (3rd screenshot) Head First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc., 2005
Question 3. "Do you need to know how to program to document web APIs?". Peter Peter Gruenbaum. Linkedin thread. https://www.linkedin.com/groups/Do-you-need-know-how-4219315.S.5872831609228509188
Question 4. "Do you need to know how to program to document web APIs?" Sara Schertz, Tech Writer / Bus. Analyst, Linkedin thread. https://www.linkedin.com/groups/Do-you-need-know-how-4219315.S.5872831609228509188
Question 5. – "How to write helpful code samples." Sarah Maddox. STC Intercom September 2014 (forthcoming)
Question 6. “Industrious engineering students (undated)” by pellethepoet Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/pellethepoet/12097798504/
Question 7. “Industrious engineering students (undated)” by pellethepoet. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/hackny/5685399451/
Question 10. "How to Solve Sudoku Puzzles Quickly and Reliably" by Conor Murphy, Accessed 28 May 2014. http://www.bigfishgames.com/blog/how-to-solve-sudoku-puzzles-quickly-and-reliably/
![Page 30: Writing code samples for API/SDK documentation](https://reader036.vdocuments.site/reader036/viewer/2022062312/554f6d0eb4c905bb178b4f23/html5/thumbnails/30.jpg)
Question 11. Head First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc., 2005.
Question 12. “Storyteller” by Kate. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/tylluan/7579135/
Question 13. “Christmas #30” by Kevin Dooley. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/pagedooley/5208532605/
Question 14. “Fireworks” by sj liew. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/sjliew/1286426141/
Question 16. "Code Design" (Chapter 9). Learning JavaScript, by Tim Wright.
Question 17. “Engineering” by Saint Louis University. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/slumadridcampus/6263551146/
Question 20. “what people throw away” by scorpions and centaurs. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/sshb/3138725794/