APIs and SDKs: Breaking Into and Succeeding in a Specialty Market

Wednesday, September 30 — 9:00am-5:00pm

Ed Marshall
Independent Contractor
Marshall Documentation Consulting

Goals of the workshop

• Learn what APIs and SDKs are, who uses them, and why
• Learn what typical documentation deliverables are for these products
• Learn a common methodology for producing documentation for APIs/SDKs from the source code, a single source of truth
• Be able to describe why this approach is preferred by many developers
• Practice using a common tool for producing documentation from the source code, Javadoc
• Learn about Web Services APIs

The popularity of cloud computing is stronger than ever. By 2017, cloud computing industry is expected to grow to a $240 billion industry. Yes, that's 'b' as in 'billion'! It’s triple the earnings of only four years ago, when earnings were $77 billion.* With this increased demand comes the need for skilled technical communicators who can document Web Services, the methods used to communicate between two devices on the Web, but few have the required skills.

• Learn recommended sources of training to get the skills needed for this area
• Create two API samples that you can show to potential clients or employers

Computer Requirements

Bring a laptop that allows you to install software. Many corporate IT departments block the software installation features on their employees' computers. You will need to install some software on your laptop. All software is provided on a thumb drive. The software used for this class runs on Windows. If you are bringing a Mac, you need to have a Windows emulator installed ahead of time and be comfortable managing the emulator.

Discussion of APIs and SDKs

• What are APIs and SDKs? How are these similar and different?
• Who uses APIs and SDKs?
• What are the typical documentation deliverables? What information should you provide to users?
• What are the benefits and drawbacks to working in this area for technical writers?
• How much do you have to read software code? What information can you get from the code and what can't you get from the code?

Javadoc discussion, Demo and Hands-on Exercises

You will complete these tasks:

• Inserting typical reference information into the source files, generating the online help, and viewing the output
• Inserting conceptual information into the source files, generating the online help, and viewing the output

Web Services APIs Discussion and Hands-on Exercises

• How Web Services are used to solve business problems
• Examples of Web Services being used and developed by widely known companies
• The common components of Web Services
• The current trends for using Web Services and why this is an important area for technical communicators

You will complete these tasks in the hands-on exercises

• Create Web Services documentation by extracting relevant, useful reference information from a REST API specification into a supplied Microsoft Word template

 

About

Ed Marshall is an independent consultant technical writer and the sole proprietor of Marshall Documentation Consulting, with over 26 years in technical writing. He specializes in technical documentation for developers including API (application programming interfaces), SDK (software developer’s kits), Web Services products, etc. Over his career, Ed has developed expertise in using tools to “let the computer do the work,” such as advanced tools for editing files, comparing files, and searching / replacing text. < /p>