api workshop: deep dive into code samples
Post on 16-Jul-2015
Embed Size (px)
API Documentation Workshop: Deep dive into code samplesBy Tom Johnsonwww.idratherbewriting.comJanuary 24, 2015
1Code SamplesCode samples are arguably the most important part of developer documentation.Code is the language developers speak.2Example of a code sample
3Another example of a code sample
4Challenges in code annotation
Head First Java, 2nd EditionScreenshot from Head First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc., 20055Why 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.
6Which 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. 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.
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.7Do 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 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.8If I could write code, wouldn't I be a developer?"We dont 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 developers guide, and the complex implementation required for a production-ready application." Sarah Maddox, API technical writer at Google. Sept 2014 Intercom issue.
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.9How do you know what's obvious without a development background?
flickrIndustrious 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. 10Can I just get all code samples from engineers?
flickrwhat 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.
11Are code samples hard to write?
"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.
12How do I add comments in code?
Head First Java, 2nd EditionHead First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc13
Head First Java, 2nd EditionHead First Java, 2nd Edition, by Bert Bates; Kathy Sierra. Published by O'Reilly Media, Inc14
15How do I provide instructions for lengthy samples?Build it up as a storyOr describe it section by section after providingthe full code.
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).16How do you explain code that is non-linear?
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/17
This is from Beginning Java 8 Fundamentals. 18Shouldn't I show our product's full capabilities?
flickrFireworks 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.
Our preconfigured visualizations
19Where 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.
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.
Prob not recommended but seems like it wouldn't be so out of the expected.21What's the best way to review code with engineers?
flickrEngineering by Saint Louis University. Licensed under a Creative Commons Attribution 2.0 Generic. Accessed 28 May 2014. https://www.flickr.com/photos/slumadridcampus/6263551146/22If I can get code to run myself, why review it?PerformanceMemoryInefficiencyBest practicesHow can I make my code samples readable?
Syntax highlighters prettify, highlight.js, etc. manual stackedit.io applies a syntax highlighter
Format the syntax well. Line up curly bracesUse a consistent style line breaks, etc.
Not all syntax highlighters are the same.24How do I avoid tedious code sample updates with new releases?
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 samples25Learning