Writing Code Samples for API Documentation

For the September 21, 2016, meeting, Joe Malin discussed writing code samples for API documentation. This meeting summary was written by Michelle Mills.

When we write API documentation our audience always already has a basic understanding:

  • Millennials have used computers since high school; all are computer literate
  • Diverse professionals (accountants, graphic designers, etc) probably know what they are and want to utilize them
  • All users are therefore also developers

Code samples are important

  • Developers want to be able to copy code from documentation
  • Code samples are fairly complete apps (not a description or tutorial)
  • Shorter is usually better (long is often too specific; specifics can be addressed in footnotes if necessary)
  • Inference links outside your organization are discouraged (continuity and accuracy cannot be guaranteed)

Your documentation should:

  • Illustrate patterns and tasks
  • Promote copy/paste
  • Be simple
  • Be applicable to “real life” issues
  • Be high quality:
    • Solves real-world problems
    • Uses programming language standards
    • Provides working samples

What is a pattern or task in API documentation? Examples include:

  • Security (OAUTH identification)
  • CRUD (create, report, update delete)
  • UI, including:
    • App navigation
    • Enhanced effects (animations, carousels)
    • Responsive UI

Specific example: Good pattern/bad writing

From Salesforce SOAP API documentation API (freely available); used to convert a “lead”:

public String[] conv() {
     String[] result = new String[4]; 
     try {
           Lead[] x = new Lead[2]; 
           Lead y = new Lead(); 
           y.setPhone(“(707) 555-0328");
           x[0] = y;
           Lead z = new Lead();
           x[1] = z; 
           SaveResult[] retr = connection.create(x);
} catch (ConnectionException e) }

Some problems:

  • No comments
  • Nonspecific variable names (i.e. x)
  • Shortened string variable names (conv instead of convert or convertLead)
  • Where did ConnectionException come from?

Code corrections for above example:

// Convert a Lead into an Account and a Contact
// Based on Enterprise WSDL setup
public String[] convertLeadRecords() {
      String[] results = new String[4];
      EnterpriseConnection myConnect; 
      try {
           Lead[] Leads = new Lead[2];
                Lead[0] = new Lead(); 
           Lead[1] = new Lead();
           SaveResult[] results = myConnect.create(Leads);
      } catch (ConnectionException connectExcept) }

Common coding errors that are easy to catch include:

  • Poor naming conventions:
    • using foo or x
    • Non-standard naming conventions, such as:
public class Myclass {
  • Non-standard indentation, such as
for (int i = 0; i < 10; i++) 
  • Forgetting the variable’s name, such as:
var destSite = ‘http://www.example.com/rest1’
response = sendRequest(destURL);
  • Accidental misuse of = and ==

Always test your code sample to be sure it works!

Good code samples include:

  • Samples that adhere to the styleguide
    • Use company-standard icons
    • Data input labels below input
    • Test on small devices
  • Coding guideline examples:
    • Mutable variable: mIncomingEvent
    • Constant: SECONDS_PER_MINUTE
    • Package names: com.example.sampleapp
  • Commenting guidelines and examples:
    • Use line or block, not both
    • Add to the sense of the code – don’t just restate the obvious
    • Add licensing info to every file (tech writers need to understand licensing and/or ask manager or legal.)

Take a piece of raw code, and apply your style, commenting, and coding guidelines. You can also generate snippets or gists from a raw code example.

Resources for licensing information:

  • Choosealicense.com
  • Github repositories

Resources for code examples:

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s