This presentation explores the challenges that building your first website for Application Programming Interface (API) documentation may present. It investigates how you can leverage minimal resources to create documentation that provides useful information to support the adoption of your API by third-party developers.

1. Presented by
Mary Linderman
Andrei Essaoulov

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

3. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 3

4. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 4

5. 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
STC Summit 2015 Survival strategies: Building your first website for API documentation 5

6. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 6

7. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 7

8. Example: TechWriter
STC Summit 2015 Survival strategies: Building your first website for API documentation 8
Business entity
Technical writer
TechWriter class
Fields:
 name
 currentProject
 workHours
Methods:
 Outlining
 Writing
 Proofreading

9. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 9

10. 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
STC Summit 2015 Survival strategies: Building your first website for API documentation 10

11. Example: TechWriter class
STC Summit 2015 Survival strategies: Building your first website for API documentation 11
Sample source code for the TechWriter class

12. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 12

13. Business value of APIs
STC Summit 2015 Survival strategies: Building your first website for API documentation 13

14. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 14

15. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 15

16. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 16

17. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 17

18. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 18

19. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 19

20. 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
STC Summit 2015 Survival strategies: Building your first website for API documentation 20

21. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 21

22. Example: Class libraries
STC Summit 2015 Survival strategies: Building your first website for API documentation 22
Method in the source code for the TechWriter class.

23. Example: Class libraries
STC Summit 2015 Survival strategies: Building your first website for API documentation 23

24. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 24

25. Example: Syntax highlighting
STC Summit 2015 Survival strategies: Building your first website for API documentation 25
Comments in green.
Reserved words in blue.
Variable names in black.

26. Example: Syntax highlighting
STC Summit 2015 Survival strategies: Building your first website for API documentation 26

27. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 27

28. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 28

29. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 29

30. Example: MadCap vs Confluence
STC Summit 2015 Survival strategies: Building your first website for API documentation 30

31. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 31

32. 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
STC Summit 2015 Survival strategies: Building your first website for API documentation 32

33. Example: Usability testing
STC Summit 2015 Survival strategies: Building your first website for API documentation 33
Shifted from API names to task-based titles for usability.

34. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 34

35. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 35

36. Example: Metadata tags
STC Summit 2015 Survival strategies: Building your first website for API documentation 36

37. Example: Metadata tags for SEO
STC Summit 2015 Survival strategies: Building your first website for API documentation 37

38. 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.
STC Summit 2015 Survival strategies: Building your first website for API documentation 38

39. Example: Naming Conventions
STC Summit 2015 Survival strategies: Building your first website for API documentation 39
Name your HTML elements and region tags.

40. 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!
STC Summit 2015 Survival strategies: Building your first website for API documentation 40

41. Questions
STC Summit 2015 Survival strategies: Building your first website for API documentation 41

42. 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
STC Summit 2015 Survival strategies: Building your first website for API documentation 42

43. 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
STC Summit 2015 Survival strategies: Building your first website for API documentation 43

44. Resources
Tools
 DoxyGen
 Google Webmaster Tools
 Javadoc
 Markdown
 NDoc3
 google-code-prettify
 Sandcastle
 Syntax Highlighter
Usability testing
 Rocket Surgery Made Easy by Steve Krug
STC Summit 2015 Survival strategies: Building your first website for API documentation 44

45. Contact Information
 Mary Linderman - linderman.mary@gmail.com
 Andrei Essaoulov - yesaulov@gmail.com
STC Summit 2015 Survival strategies: Building your first website for API documentation 45