Presentation from STC New England Interchange Conference (March 27 - 28)

1. APIs and SDKs: Breaking into
a Specialty Market
STC New England Interchange
Ed Marshall
Copyright 2015

2. APIs and SDKs
API = Application Programming Interface
SDK = Software Development Kit
• Typical users and why they use them
• Typical producers of these products
• Examples
2

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

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

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

6. Reference Information for APIs
• Brief description
• Syntax
• Examples, examples, examples!
• Error messages
• Cross-references
6

7. Key Programming Concepts
• Data types and variables
• Program control – loops, conditions, etc.
• Logical operators
• Data structures, such as arrays
• Functions and methods
7

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

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

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

11. Typical Skills Needed
• Good writer, but not great
• Strong organizational skills
• Proactive in getting information
• Have a flair for tools
11

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

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

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

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

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

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

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

19. Automated Tools
• Doxygen
• Javadoc
• Sandcastle – Tool for .NET help (MSDN style)
19

20. Microsoft IDEs
• Visual Studio 2008 Visual C++
• Visual C #
• Visual Basic
• Visual J#
All free from
www.microsoft.com/express/download/
20

21. Other IDEs
• NetBeans –
netbeans.org/downloads/index.html
• Eclipse – www.eclipse.org (a free open source
IDE)
21

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

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

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

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

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

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

28. 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).

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

30. 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”.

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

32. Determining Which Help Format to Use
• Platforms
• Browsers
• Minimum versions required by your product
32

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

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

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

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

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

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

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

40. Typical Daily Activities
1. 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

41. Summary
• Description of APIs and SDKs
• Benefits to writers
• Drawbacks to writers
• Training
• Writing considerations (tools, formats, issues
for context-sensitive help)
41

42. Closing
• Thank you.
• Questions?
Ed Marshall
Marshall Documentation Consulting
ed.marshall@verizon.net
www.MarshallDocumentationServices.com
LinkedIn: Ed Marshall
Twitter: EdMarshall
+1 978-339-3095
42