survival strategies: building your first website for api documentation

Presented by

Mary Linderman Andrei Essaoulov

Welcome Introduce basic concepts underlying developer

documentation.

Explore ways to develop your technical skills.

Discuss content and code samples to include in API documentation.

Explore how to choose tools for developing your website.

Investigate simple strategies for usability testing.

Discuss optimizing your website for searching.

Describe possible opportunities for automation.

STC Summit 2015 Survival strategies: Building your first website for API documentation 2

Goals for this presentation Offer a vocabulary for discussing API writing.

Supply key takeaways for building your first website.

Provide insights for the future development of your site.


What is an API? API is an acronym for application programming

interface.

Includes the tools used by third-party developers to build applications on an existing code base.

Public code used to reference functionality already implemented by an internal development team.


What is an SDK? SDK is used to represent software development kit.

SDK includes the following tools:

Libraries containing the code referenced by third-party developers

Utilities used to facilitate implementing an application

Code samples illustrating how to use your API

Other resources


Object-oriented (OO) languages OO programming languages includes C#, Java, C++,

Objective-C, and other languages.

Models code on real-world or business entities.

Used to implement backend code that controls the functionality or features exposed in the API.


Example: API for a Tech Comm App Includes a technical writer as a business entity.

Implements a class called TechWriter.

Add fields or properties to the class, such as name, current project, and work hours.

Add methods used to determine the behavior of a writer, such as outlining, writing, and proofreading.


Example: TechWriter


Business entity

Technical writer

TechWriter class

Fields:

name

currentProject

workHours

Methods:

Outlining

Writing

Proofreading

Working with an API A developer works with the API to perform these tasks:

Uses the class as a template to add multiple technical writers to the application. They are called instances.

Implements code that assigns tasks to these instances.


Working with an API API writer works with the API to document:

How to create these class instances

How to set their properties

How to use the methods that control their behavior


Example: TechWriter class


Sample source code for the TechWriter class

Business value of APIs Provide a way for developers to make unique services

or data available to customers.

Support custom applications or integrate functionality on a website to attract customers.

Generate significant revenue for company, as exemplified by Expedia, eBay, Twitter, and Google.


Business value of APIs


Adoption strategy - API writer Understand your organization’s adoption strategy to

facilitate adoption.

Works with product management to identify the significant features of the API.

Use adoption goals as context to frame the presentation of the API’s technical components.

Develop information about how to use the API for building applications or accessing services.


Adoption strategy - resources Use the adoption strategy to identify required writing

resources.

Request developer time for reviewing content, writing code samples, and creating sample applications.

Identify tools, additional writers, or other resources needed for the documentation.


Ramp up your technical skills Identify the programming language and other

technologies used to build the API.

Use this information for these purposes:

To enhance your technical vocabulary.

To develop your ability to read code samples.

To improve interactions with development teams.

To produce well-written documentation.


What is an IDE? IDE is an integrated development environment.

Used by your developers to write code.

Provides a specialized editor for writing code.

Supports building the libraries provide as part of the API.


Explore the IDE Install the IDE on your computer.

Work through tutorials that explain how to use the IDE.

Get familiar with the IDE to understand how developers build applications using your API.


Experiment with the API’s language Take advantage of free learning opportunities:

MSDN - Microsoft provides free videos and training materials in C#.

The Java Tutorials - Oracle offers free training in Java.

Check out study guides for language certifications with overviews of key language features.

Build the sample applications to learn about features of the language.

Plan about twenty hours to ramp up on terminology and understand basic code samples.


Content for your first API website Consider the audience for your API documentation.

Write for users with a range of technical expertise:

Entry-level developers just out of college

Developers with no prior background in the technology used by your API

Experienced developers who just want information about a specific API feature


Common types of content Concept information - a high-level overview of the

API architecture, and other features.

Getting started materials - instructions for installing the SDK, setting up an dev environment, and implementing a sample application.

Code samples - includes fragments of code, detailed code samples, and sample applications.

Reference or class libraries – includes developer comments and other information automatically generated from elements in the API source code.


Example: Class libraries


Method in the source code for the TechWriter class.

Example: Class libraries


Code samples Include well-written code samples for all key API

operations.

Establish a clear strategy for writing code samples with your development team.

Reuse code from sample applications or QA test cases.

Use syntax highlighting to enhance readability by color coding specific words in your code samples.


Example: Syntax highlighting


Comments in green.

Reserved words in blue.

Variable names in black.

Example: Syntax highlighting


Types of code samples Short snippets - illustrate a single feature discussed

in your conceptual or overview content. This code may consist of two or three lines.

Codes samples for methods or classes - provide a detailed example of a specific API feature. They may be used in a tutorial, and consist of ten or more lines.

Sample applications - illustrate complex projects and application design with your API. These samples may include multiple files.


Tools for building your site Tools for writing conceptual content, tutorials, and

other explanatory material, such as Madcap Flare, Robohelp, Confluence, oXygen, or Epic.

Tools for generating the class libraries, such as Sandcastle, Javadoc, DoxyGen, or NDoc3.

Repository for storing source code influences the collaboration of writers and developers while updating code comments.


Evaluate tool features Authoring and collaboration capabilities.

Learning curve for the documentation team and SMEs.

General web publishing functionality.

Search and content tagging.

Community capabilities.

Options for integrating with source control products.

Flexible formatting and other customization options.

Costs for proprietary versus open source tools.

Compatibility with other tools used by your 0rganization.


Example: MadCap vs Confluence


Investigate your user’s experience Learn about how developers navigate your website and

their expectations for it.

Take a no frills approach to usability testing as described in Rocket Surgery Made Easy by Steve Krug.

Devise usability tests tailored to your API and audience.

Structure your usability tests to take about an hour, so they are a minimal investment of time.


Performing usability testing Consider recruiting these test subjects and look for common usability issues:

External developers who want to used your API

Current developers working on projects other than the API

New hires for development teams, including entry-level and experienced developers


Example: Usability testing


Shifted from API names to task-based titles for usability.

What is SEO? An acronym for search engine optimization.

Includes the process of ensuring that your content is discoverable by major search engines.

Involves identifying general information about how search engines index the contents of your site.


Use SEO to enhance usability Learn about developer preferences for searching rather

than browsing information.

Use analytics to identify major search engines used to find information about your public APIs and the terms being searched.

Add metadata and use other techniques to ensure that search engines return your pages.

Test searching on your site.


Example: Metadata tags


Example: Metadata tags for SEO


Look for automation opportunities Use content modelling to establish a semantic structure based on

information types, such as concepts, tasks, references, or samples.

Identify manual tasks used to build your API documentation project: Generating class libraries - tools used to generate this highly

structured content provide output that you produce by an automated build process.

Code samples - explore an automated solution for adding them to the website, which ensures that they stay up-to-date.

Establish consistent naming conventions for files and other content elements to facilitate building integration points in your documentation project.

Learn an OS scripting language, such as shell, batch file programming, or PowerShell.


Example: Naming Conventions


Name your HTML elements and region tags.

Strategize for the future Look for opportunities to balance current goals with

the future growth and evolution of your site.

Watch for new trends in technical communications to help you strategize for future iterations of your site.

Continually reassess the needs of your developer community.

Use the strategies discussed here to organize your goals and resources.

Devise a successful survival strategy! Don’t get voted off the island!


Questions


Resources API writing Lessons Learned as a Novice API Writer by Mary Linderman in

Intercom (September 2014)

Business value and adoption strategies APIs: A Strategy Guide by Jacobsen, Brail, and Woods APIs can be strategic tools to unlock business values by Teresa Tung

and Michael J. Blitz Explaining the API Revolution to your CEO by Dan Woods The Strategic Value of APIs by Bala Iyer and Mohan Subramaniam


http://www.intercom.stc.org/

http://www.amazon.com/dp/1449308929/?tag=googhydr-20&hvadid=57197490520&hvpos=1t2&hvexid=&hvnetw=s&hvrand=531767601370265643&hvpone=23.50&hvptwo=&hvqmt=b&hvdev=c&ref=pd_sl_8td6j9cqe0_b

http://www.computerweekly.com/feature/APIs-can-be-strategic-tools-to-unlock-business-value

http://www.forbes.com/sites/danwoods/2011/12/15/explaining-the-api-revolution-to-your-ceo/

https://hbr.org/2015/01/the-strategic-value-of-apis

Resources Technical skills Exam Ref 70-483: Programming in C# by Wouter De Kort Head First C# by Jennifer Greene and Andrew Stellman Head First Java by Kathy Sierra and Bert Bates

Sample API documentation Android Flickr Java™ Platform API Specification Jquery .NET Framework Class Library Vimeo


http://www.amazon.com/Exam-Ref-70-483-Programming-MCSD/dp/0735676828



http://www.headfirstlabs.com/books/hfcsharp/

http://shop.oreilly.com/product/9780596009205.do

https://developer.android.com/guide/index.html

https://www.flickr.com/services/api/

http://docs.oracle.com/javase/7/docs/api/

https://api.jquery.com/

https://msdn.microsoft.com/en-us/library/gg145045(v=vs.110).aspx

https://developer.vimeo.com/api/start

Resources Tools DoxyGen

Google Webmaster Tools

Javadoc

Markdown

NDoc3

google-code-prettify

Sandcastle

Syntax Highlighter

Usability testing Rocket Surgery Made Easy by Steve Krug


http://sourceforge.net/projects/ndoc3/

https://www.google.com/webmasters/

http://www.oracle.com/technetwork/articles/java/index-137868.html

http://whatismarkdown.com/

http://sourceforge.net/projects/ndoc3/

https://code.google.com/p/google-code-prettify/wiki/GettingStarted





https://sandcastle.codeplex.com/

http://alexgorbatchev.com/SyntaxHighlighter/

http://www.amazon.com/dp/0321657292/?tag=googhydr-20&hvadid=36583707146&hvpos=1t1&hvexid=&hvnetw=s&hvrand=18130167530348743633&hvpone=26.48&hvptwo=&hvqmt=b&hvdev=c&ref=pd_sl_txbulvhsv_b

Contact Information Mary Linderman - [email protected]

Andrei Essaoulov - [email protected]


survival strategies: building your first website for api documentation

Software

api documentation

api api writer

api writing

survival strategies

techwriter stc summit

techwriter class stc

behavior stc summit

resources stc summit