apis and sdks: breaking into a specialty market
TRANSCRIPT
APIs and SDKs: Breaking into a Specialty Market
STC New England Interchange
Ed Marshall
Copyright 2015
APIs and SDKs
API = Application Programming InterfaceSDK = Software Development Kit
• Typical users and why they use them• Typical producers of these products• Examples
2
Typical Documentation Deliverables• Programmer’s Reference Guides (often
delivered online in some format)• Programmer’s Guides• Performance & Tuning Guides• API and SDK Installation Manuals
3
Ideal Information for SDKs
• Provide an overview of the SDK• Describe the tools and components in the SDK
and how they relate to the APIs• Describe each tool in detail• Describe any sample programs included in the
SDK
4
Ideal Information for APIs
• Break each component into the various families
• Describe each API completely, including cross-references to any types used in the definition
• Provide and explain examples that show both trivial and complex use of the class/API
5
Reference Information for APIs
• Brief description• Syntax• Examples, examples, examples!• Error messages• Cross-references
6
Key Programming Concepts
• Data types and variables• Program control – loops, conditions, etc.• Logical operators• Data structures, such as arrays• Functions and methods
7
Benefits to the Writer
• Do more advanced technical writing = Higher pay, higher status
• Good if you like to play with software at the code level, create and test examples, talk and write in gibberish
• Work more closely with developers
8
Drawbacks to the Writer
• Possibly restrictive/repetitive writing• Possibly less contact with users as they are
developers/programmers themselves• Possibly, more technically challenging
development/build environments
9
Knowledge/Personality Traits that Work Well
• Some knowledge of programming languages BUT you don’t have to be a programmer!
• Willingness to work with advanced/programmer types of tools – Use software instead of specs
• Desire to work at the code level and write for developers who work at the code level
• Willingness/confidence to work closely with senior developers
• Ability to develop context-sensitive level help at a lower level than the typical end-user (window-level) help
10
Typical Skills Needed
• Good writer, but not great• Strong organizational skills• Proactive in getting information• Have a flair for tools
11
Ways to Add Value• Organizing information – change from timeline to
alphabetical, grouping by categories of function, etc.• Adding missing information• Removing info not needed• Correcting discrepancies/non-parallel
formats/descriptions• Using terms consistently• Providing better definitions – meaningful, not just
repeating the function
12
Ways to Add Value, cont.
• Providing usage notes• Recommending sequence of use – flowcharts• Alphabetizing lists of error messages
(removing duplicates)• Correcting spelling via custom spell-check
dictionaries
13
Ways to Get Information
• Read the code*• Run automated tools against the software*• Provide fill-in-the-blank templates to
developers*• Use the software• Read the specifications• Attend demos
* Recommended as the best methods for gathering information 14
What to Look for in the Code
Look in both internal/external files/functions for:• Function calls• Function parameters and data types• Return values• Enums, structs, etc.• Error codes
15
Information You Can’t Get from Reading the Code
• Why someone would use a certain function • The recommended logic flow – the order in
which functions need to be called • Background information• Usage notes• Relationships between functions (get/set,
open/close, etc.), but can deduce these and verify with developers
16
Possible Strategies/Timeline for Accessing Code
1. Edit comments in code but don’t make changes in the code – shows you know the difference between comments and code.
2. Learn how to generate output from code and demonstrate “safe computer practices” – Do test builds and verify against known good builds.
3. Commit to only changing comments – and stick to it.4. Best practice: Build outputs locally using the company’s
system before checking in changes – builds trust in your work.
17
Writing Style Differences
• Use active voice.• Sentence fragments are acceptable.• Use verbs/gerunds to start phrases.• Eliminate “useless” words that are noise to
developers.
18
Automated Tools
• Doxygen • Javadoc• Sandcastle – Tool for .NET help (MSDN style)
19
Microsoft IDEs• Visual Studio 2008 Visual C++• Visual C #• Visual Basic• Visual J#
All free from www.microsoft.com/express/download/
20
Other IDEs
• NetBeans –netbeans.org/downloads/index.html
• Eclipse – www.eclipse.org (a free open source IDE)
21
Doxygen• Very powerful code generation tool• Free• Reads specially formatted comments in code• Supports C/C++, Java, Python, IDL, and C#• Outputs RTF, compiled HTML Help, browser-based help, and
LaTex (PDF)• Compatible with Javadoc 1.1• Active development/support• www.stack.nl/~dimitri/doxygen/download.html#latestsrc –
current version is 1.8.9.1 (January 2015)
22
Javadoc
• Powerful and free code generation tool for Java• Reads specially formatted comments in code• Outputs browser-based help• Active development• Current version: Java Development Kit 7.0 Update
51 –www.oracle.com/technetwork/java/javaee/downloads/index.html?ssSourceSiteId=ocomen
• www.doclet.com – source for Java Doclets and Javadoc information
23
Web Services – A Growing Area
• Web Service - An application that provides a Web API to provide a platform / language independent application
• Related to service-oriented architectures (SOAs)
• Uses several protocols to send / receive XML messages
Who Uses Web Services
• Financial – mortgage companies, institutional traders, banks, etc.
• Web retail – Amazon Web Services, Nokia, and Netflix
• Software – Google and Dyn• Social Media – Twitter, Flickr, Picasa, You
Tube, Facebook, and Linked In
Types of Web Services
• REST – Representational State Transfer• SOAP – Simple Object Access Protocol• XML-RPC – XML Remote Procedure Call• JSON-RPC – JavaScript Object Notation
Remote Procedure Call
REST (Representational state transfer)
• RESTful APIs do not require XML-based web service protocols (SOAP and WSDL) to support their interfaces.
• REST is not a protocol, but a set of architectural principles. REST services provide simpler interfaces, all resources are identified in the request, and you can manage the resources from the REST API.
• REST services offer an easy-to-parse URL structure, that identifies the categories of data available.
• REST services uses standard HTTP methods.
SOAP (Simple Object Access Protocol)
• Defines the communication method and the structure of the messages. Uses XML for the data.
• A SOAP service publishes a definition of its interface in a machine-readable document, using WSDL (Web Services Definition Language).
Web Services / SOA Resources
• Web Services A Manager’s Guide – Anne Thomas Mannes
• Service Oriented Architecture for Dummies –Judith Hurwitz, Robin Bloor, and Carol Baroudi
• Developing User Assistance for Mobile Apps –Joe Welinske
Summary• Fast growing field – In 2014, cloud computing industry was
expected to grow to a $150 billion industry.• Combines traditional tech. writing w/ API skills > higher
pay, more flexibility, not as boring work• Work with “cool” (fun) technologies (Amazon, music,
photos, messaging, etc.)• Gets you into revenue generating areas such as
marketing, not just “cost centers”.
Build and Deployment Issues
• Use of automated build systems• Use of source code control systems• Other tools to do file comparisons, advanced
text editors, multi-file search and replace, etc.
31
Determining Which Help Format to Use
• Platforms • Browsers• Minimum versions required by your product
32
Help Formats• HTML Help 1.x• WebHelp/Web Help • WinHelp – Not in Vista/Windows 7/Windows Server 2008.
Download the WinHelp viewer from support.microsoft.com/kb/917607
33
Context-sensitive Help
• Need to determine if it is necessary• Need developers to implement/hook to the API• Have to use the appropriate API for the help
format• Mapping of context IDs to numbers/text strings• Need to test all links from the product
34
Sample APIs• Google Earth API – earth.google.com/comapi/• Google Maps API – code.google.com/apis/maps/• JavaScript The Definitive Guide - David Flanagan• Sun Java documentation• Microsoft Tablet PC SDK documentation -
msdn.microsoft.com/en-us/library/ms840465.aspx• http://developers.box.com/docs/• http://php.net/docs.php• Amazon Web Services - http://aws.amazon.com/
35
Breaking into this Market
• Get training to develop the skills:- Courses – www.coursera.org- Self-paced training- On-the-job training
• Make your own sample help systems, with context-sensitive help coded
• Write some sample programs
36
Self-Paced Training• Manuel Gordon’s API materials
(www.gordonandgordon.com)• Documenting APIs: Writing Developer
Documentation for Java APIs/SDKs – James Bisso (www.bitzone.com/book.html)
• Deitel & Deitel “(C/C++/C#/Java) How to Program” • Sams “Teach Yourself…” • Sample projects, such as the HTML Help API • www.coursera.org
37
Listservers and Other Groups• STC API – groups.yahoo.com/group/svcstcapi/• API writers – groups.yahoo.com/group/APIWriters/• HATT – groups.yahoo.com/group/HATT/• MSHelp 2.0 – groups.yahoo.com/group/MSHelp2/• Eclipse – groups.yahoo.com/group/eclipse_tw/Linked In Groups:• API Documentation• Java API• Framework and API Designers• Technical Writers and SDK Doc
38
Common Tools Used• Windows, Unix, and Linux• Build scripts• Source code control tools (Visual SourceSafe,
SVN, Perforce, etc.)• Various IDEs (MS Visual Studio, NetBeans,
Eclipse, etc.)• Comparison/differencing tools (Beyond Compare)
39
Typical Daily Activities1. Check nightly build logs for failures/check-ins.2. Update Perforce – look for changes to doc.3. Research any changes to APIs, error messages,
etc.4. Check bug system for my assigned bugs, changes
to bugs I’m following, new API-related bugs.5. Download and install new kits (if it’s safe to do so).6. Document new features/changes to APIs.
40
Summary
• Description of APIs and SDKs • Benefits to writers• Drawbacks to writers• Training• Writing considerations (tools, formats, issues
for context-sensitive help)
41
Closing• Thank you.• Questions?
Ed MarshallMarshall Documentation Consulting
LinkedIn: Ed MarshallTwitter: EdMarshall+1 978-339-3095
42