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
1. What are code
Usually supplementary material that accompanies
API or SDK reference documentation (particularly
Can be short or lengthy, full of comments and
explanation or without any explanation at all.
Great example on jquery's documentation here:
Another good example:
2. Why add code
Code samples are in another language. If audience
speaks the language, the code communicates more
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.
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.
4. Do I need to be a
programmer to write code
"… 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 /
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
6. How do you know what's
obvious without a dev
7. Can I just get all code
samples from engineers?
8. How can I learn
12. How do I provide
instructions for lengthy
Build it up as a story
Or describe it section by
section after providing
the full code.
13. How do you explain
code that is non-linear?
14. Shouldn't I show our
product's full capabilities?
15. Where do you put
Option 1: Separate from the reference material?
Keeps reference material clean and minimal, but not
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.
16. Can I adopt a playful,
irreverent tone with dev
"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
17. What's the best way to
review code with
18. If I can get code to run
myself, why review it?
20. How do I avoid tedious
updates with new
The 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
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-
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.
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 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/