API Workshop: Deep dive into code samples
•Download as PPTX, PDF•
3 likes•2,359 views
See http://idratherbewriting.com for more details. This was the third slidedeck I used in my presentation. Most of these slides repeat what I presented as a soap! conference webinar in Poland.
Recommended
More Related Content
What's hot
What's hot (18)
Similar to API Workshop: Deep dive into code samples
Similar to API Workshop: Deep dive into code samples (20)
More from Tom Johnson
More from Tom Johnson (6)
Recently uploaded
Recently uploaded (20)
API Workshop: Deep dive into code samples
- 1. API Documentation Workshop: Deep dive into code samples By Tom Johnson www.idratherbewriting.com January 24, 2015
- 2. Code Samples • Code samples are arguably the most important part of developer documentation. • Code is the language developers speak.
- 3. Example of a code sample
- 4. Another example of a code sample
- 5. Challenges in code annotation Head First Java, 2nd Edition
- 6. 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.
- 7. 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.
- 8. 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
- 9. 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.
- 10. How do you know what's obvious without a development background? flickr
- 11. Can I just get all code samples from engineers? flickr
- 12. Are code samples hard to write?
- 13. How do I add comments in code? Head First Java, 2nd Edition
- 14. Head First Java, 2nd Edition
- 16. How do I provide instructions for lengthy samples? • Build it up as a story • Or describe it section by section after providing the full code.
- 17. How do you explain code that is non- linear?
- 19. Shouldn't I show our product's full capabilities? flickr
- 20. 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.
- 21. 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.
- 22. What's the best way to review code with engineers? flickr
- 23. If I can get code to run myself, why review it? • Performance • Memory • Inefficiency • Best practices
- 24. How can I make my code samples readable?
- 25. How do I avoid tedious code sample updates with new releases?
- 26. LEARNING CODE
- 27. How can I learn programming? • safariflow.com • safaribooksonline.com • lynda.com • teamtreehouse.com • codeschool.com • udemy.com
- 28. How can I keep my brain from exploding?
- 29. 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.
- 31. Image credits Slide 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/
Editor's Notes
- Screenshot from Head First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc., 2005
- Web APIs – one example is REST API. Different paths return different kinds of information usually in JSON format. You access the paths via http URLs, knowing the right options and parameters to add on the end of URLs and so forth. Code agnostic. However, many APIs have ways to more easily work with the calls in the language someone is programming in. Example: JavaScript SDK. If code samples are simply curl requests and responses, that's one thing. If the code samples are more elaborate, though, it's quite another challenge.
- You need some programming knowledge. The more you know, the more powerful you are. Code samples are usually rather simple. You focus on the product, not the programming language.
- This is like saying, if I can write a sentence, couldn't I write a novel? Writing an application is a much more complex endeavor that writing some code samples. Code samples are simple and focus on the nuts and bolts of how your particular product works.
- “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. You need an awareness. Need to know terminology. The more you know about the particular language, its constraints, etc., the better writer you'll be. Experience in creating some video tutorials showing how the SDK worked. "call a method" versus "run a method". Getting the language right so it didn't seem odd. Developers almost always overestimate their audience, so go with gut and err on the side of too much explanation. Sample story: how to change font in a widget. Product mgr desperately wanted info, while dev said it's obvious to the user.
- “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/ Engineers aren't going to hand write every example you'll need. Engineers may show you the pattern that you can then extract for other examples. Engineers may give you a chunk of code but then fail to explain much of it, or give a really terse explanation. Engineers like to work with code a lot more than documentation, so they'll probably be happy to talk through the code. But it may be hard for them to articulate it in a language you can understand if you don't know the programming language.
- "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/ Story of the sudoku puzzle. Code like this: something about it keeps my brain engaged. This can be a lot of fun. Kind of like solving math problems. Writing code samples can be fun. Taps more into the "figuring-out" mode of your brain, which makes tech writing more engaging.
- Head First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc
- Head First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc
- “Storyteller” by Kate. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/tylluan/7579135/ Build it up as a story. Divide it up section by section Can refer to different parts of the code via line numbering. If users don't get it, they might not be ready for it (the complexity is beyond their level).
- “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/
- This is from Beginning Java 8 Fundamentals.
- “Fireworks” by sj liew. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/sjliew/1286426141/ Working examples of code that demonstrates a full feature in action. More extensive than a simple code sample, but not a production-level application. Demo app Our preconfigured visualizations
- Tell story about how you created a code samples section, separate from the sdk. There are just so many different scenarios to cover. REST API didn't need so many code samples, just a getting started section. Sometimes it's really complicated or at least non-intuitive about how to get certain info. example: suppose you wanted to show a graphic that shows a players current level, their next level, and the progress in between.
- "Code Design" (Chapter 9). Learning JavaScript, by Tim Wright. Prob not recommended but seems like it wouldn't be so out of the expected.
- “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/
- Syntax highlighters – prettify, highlight.js, etc. manual – stackedit.io applies a syntax highlighter Format the syntax well. Line up curly braces Use a consistent style – line breaks, etc. Not all syntax highlighters are the same.
- Lengthy code samples seem beautiful when published. Then bam, there's an update to the endpoints. Having to redo the code sample is a major pain. Let this be a reminder to keep code samples simple. If a feature is new, let it settle a bit before doing extensive code samples
- Lots of resources online. Free access via your library. Community college courses. A good tech writer learns on his or her own. Otherwise how could you possibly learn all you need to know and stay current in this field? Lynda.com cool but not always that helpful b/c it's harder to pause, rewind, stop, think about video. Which language do you start learning? The one you need to know. Lots of jobs for java, c++, .net, javascript. Future languages: clojure, scala
- My favorite app and method. The pomodoro method. Try splitting up your time – 1 in the morning, 1 at lunch, and 1 in the evening. You'll be amazed at how much progress you can make if you keep this pace up. Start with real contexts – this can be helpful. Start with something you're doing at work. It makes the learning so much more real and relevant. Head Start books are my favorite – really good intros. Wake up early. Brain is fresher earlier in the morning. Carve out a chunk of time at work to learn it – esp. ethical if it relates to something you're doing (rather than just learning some extraneous computer language).