Transcript
Page 1: API Workshop: Deep dive into code samples

API Documentation Workshop: Deep dive into code samples

By Tom Johnson

www.idratherbewriting.com

January 24, 2015

Page 2: API Workshop: Deep dive into code samples

Code Samples

• Code samples are arguably the most important part of developer documentation.

• Code is the language developers speak.

Page 3: API Workshop: Deep dive into code samples

Example of a code sample

Page 4: API Workshop: Deep dive into code samples

Another example of a code sample

Page 5: API Workshop: Deep dive into code samples

Challenges in code annotation

Head First Java, 2nd Edition

Page 6: API Workshop: Deep dive into code samples

Why add code samples?

• Code samples are in another language. If audience speaks the language, the code communicates more clearly to them.

• 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.

Page 7: API Workshop: Deep dive into code samples

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 8: API Workshop: Deep dive into code samples

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 9: API Workshop: Deep dive into code samples

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. Sept 2014 Intercom issue.

Page 10: API Workshop: Deep dive into code samples

How do you know what's obvious without a development background?

flickr

Page 11: API Workshop: Deep dive into code samples

Can I just get all code samples from engineers?

flickr

Page 12: API Workshop: Deep dive into code samples

Are code samples hard to write?

Page 13: API Workshop: Deep dive into code samples

How do I add comments in code?

Head First Java, 2nd Edition

Page 14: API Workshop: Deep dive into code samples

Head First Java, 2nd Edition

Page 15: API Workshop: Deep dive into code samples
Page 16: API Workshop: Deep dive into code samples

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 17: API Workshop: Deep dive into code samples

How do you explain code that is non-linear?

Page 18: API Workshop: Deep dive into code samples
Page 19: API Workshop: Deep dive into code samples

Shouldn't I show our product's full capabilities?

flickr

Page 20: API Workshop: Deep dive into code samples

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 21: API Workshop: Deep dive into code samples

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 22: API Workshop: Deep dive into code samples

What's the best way to review code with engineers?

flickr

Page 23: API Workshop: Deep dive into code samples

If I can get code to run myself, why review it?

• Performance

• Memory

• Inefficiency

• Best practices

Page 24: API Workshop: Deep dive into code samples

How can I make my code samples readable?

Page 25: API Workshop: Deep dive into code samples

How do I avoid tedious code sample updates with new releases?

Page 26: API Workshop: Deep dive into code samples

LEARNING CODE

Page 27: API Workshop: Deep dive into code samples

How can I learn programming?

• safariflow.com

• safaribooksonline.com

• lynda.com

• teamtreehouse.com

• codeschool.com

• udemy.com

Page 28: API Workshop: Deep dive into code samples

How can I keep my brain from exploding?

Page 29: API Workshop: Deep dive into code samples

How can I keep from forgetting it as soon as I switch projects?

• You have to play around with code to learn it. When you learn a concept, try to demonstrate how to do it in some sample code. Without this, the learning doesn’t really sink in.

Page 30: API Workshop: Deep dive into code samples

Tom Johnsonhttp:/idratherbewriting.com@tomjohnson

Page 31: API Workshop: Deep dive into code samples

Image creditsSlide 5: Screenshot from Head First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc., 2005

Slide 7: “Which language should the code samples be in?” Quote from Peter Peter Gruenbaum. Linkedin thread. https://www.linkedin.com/groups/Do-you-need-know-how-4219315.S.5872831609228509188

Slide 8. "Do you need to know how to program to document web APIs?” Quote from Sara Schertz, Tech Writer / Bus. Analyst, Linkedin thread. https://www.linkedin.com/groups/Do-you-need-know-how-4219315.S.5872831609228509188

Slide 9. "How to write helpful code samples.” Quote from Sarah Maddox. STC Intercom September 2014.

Slide 10. “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/

Slide 11. Engineers. Photo from Flickr.

Slide 12. "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/

Slide 13, 14. Head First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc., 2005.

Slide 16. “Storyteller” by Kate. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/tylluan/7579135/

Slide 17: “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/

Slide 19. “Fireworks” by sj liew. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/sjliew/1286426141/

Slide 21. "Code Design" (Chapter 9). Learning JavaScript, by Tim Wright.

Slide 22 “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/

Slide 25. “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/


Top Related