APIs and SDKs: Breaking Into and Succeeding in a Specialty Market Ed Marshall Copyright 2009

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

API = Application Programming Interface

SDK = Software Development Kit

Typical users and why they use them

Typical producers of these products

Examples

Typical Documentation Deliverables Programmer’s reference guides Online help (in some format, more later) Performance & Tuning Guides Programmer’s guides Data dictionaries API and SDK installation manuals System administrator's guides User configuration guides

Programmer’s reference guides

Online help (in some format, more later)

Performance & Tuning Guides

Programmer’s guides

Data dictionaries

API and SDK installation manuals

System administrator's guides

User configuration guides

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

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

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

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

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

Brief description

Syntax

Examples, examples, examples!

Error messages

Cross-references

Examples of API / SDK Documentation Visual Basic ActiveX Control Help Sample – print and online help C++ API Help Sample – print and online help Typical SDK documentation – Guide to Tools, Programmer’s Reference, Programmer’s Guide, etc.

Visual Basic ActiveX Control Help Sample – print and online help

C++ API Help Sample – print and online help

Typical SDK documentation – Guide to Tools, Programmer’s Reference, Programmer’s Guide, etc.

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

Data types / variables

Program control – loops, conditions, etc.

Logical operators

Data structures such as arrays

Functions / methods

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 / test examples, talk / write in gibberish Work more closely with developers

Do more advanced technical writing = Higher pay / higher status

Good if you like to play with software at the code level, create / test examples, talk / write in gibberish

Work more closely with developers

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

Possibly restrictive / repetitive writing

Possibly less contact with users as they are developers / programmers themselves

Possibly, more technically challenging development / build environments

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

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

Knowledge / Personality Traits, cont. Willingness / confidence to work closely with senior developers Ability to develop context-sensitive level help at a lower-level than typical end-user (window-level) help

Willingness / confidence to work closely with senior developers

Ability to develop context-sensitive level help at a lower-level than typical end-user (window-level) help

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

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

Ways to Add Value, cont. Providing usage notes Recommending sequence of use – flow charts Alphabetizing lists of error messages (removing duplicates) Correcting spelling via custom spell-check dictionaries

Providing usage notes

Recommending sequence of use – flow charts

Alphabetizing lists of error messages (removing duplicates)

Correcting spelling via custom spell-check dictionaries

Ways to Get Information Read the code - * Use the software Read the specifications Attend demos Run automated tools against the software - * Provide fill-in-the-blank templates to developers - *

Read the code - *

Use the software

Read the specifications

Attend demos

Run automated tools against the software - *

Provide fill-in-the-blank templates to developers - *

What Code Files Do You Need? C: .c files header files (.h files) other files: error files Java: .java files C++ .cpp files Header files (.h files) C#: .cs files

C:

.c files

header files (.h files)

other files: error files

Java:

.java files

C++

.cpp files

Header files (.h files)

C#:

.cs files

Information You Get from the Code Look in both internal / external files / functions for: Function calls and signatures Return values Enums, structs, etc. Error codes

Look in both internal / external files / functions for:

Function calls and signatures

Return values

Enums, structs, etc.

Error codes

Information You Can’t Get from 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

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

Generating Docs from the Code “ A single source of truth!” Common tools used: Doxygen JavaDoc Sandcastle – New tool for .Net help (MSDN style) – Doc-to-Help only HAT to support this. Others

“ A single source of truth!”

Common tools used:

Doxygen

JavaDoc

Sandcastle – New tool for .Net help (MSDN style) – Doc-to-Help only HAT to support this.

Others

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.5.8 (Dec. 08)

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.5.8 (Dec. 08)

JavaDoc Powerful code generation tool for Java Free Reads specially formatted comments in code Outputs browser-based help Active development www.sun.com – current version: Java Development Kit 5.0 Update 15 www.doclet.com – source for Java Doclets and Javadoc information

Powerful code generation tool for Java

Free

Reads specially formatted comments in code

Outputs browser-based help

Active development

www.sun.com – current version: Java Development Kit 5.0 Update 15

www.doclet.com – source for Java Doclets and Javadoc information

Possible Strategies / Timeline for Accessing Code Edit comments in code but don’t make changes in code – shows you know the difference between comments & code. Learn how to generate output from code and demonstrate “safe computer practices”– Do test builds and verify against known good builds. Commit to only changing comments – and stick to it. Best practice: build outputs locally using the company’s system before checking in changes – builds trust in your work.

Edit comments in code but don’t make changes in code – shows you know the difference between comments & code.

Learn how to generate output from code and demonstrate “safe computer practices”– Do test builds and verify against known good builds.

Commit to only changing comments – and stick to it.

Best practice: build outputs locally using the company’s system before checking in changes – builds trust in your work.

Templates Show and discuss a typical template containing the sections / information that should be included for each function.

Show and discuss a typical template containing the sections / information that should be included for each function.

Writing Style Differences Use active voice Sentence fragments are acceptable Use of verbs / gerunds to start phrases Eliminate “useless” words that are noise to developers

Use active voice

Sentence fragments are acceptable

Use of verbs / gerunds to start phrases

Eliminate “useless” words that are noise to developers

Microsoft IDEs Visual C Visual C# Visual Basic Visual J# All free from http://www.microsoft.com/express/download/

Visual C

Visual C#

Visual Basic

Visual J#

All free from http://www.microsoft.com/express/download/

Other IDEs Sun NetBeans – www.sun.com (Free - search for NetBeans) Eclipse – www.eclipse.org (a free open source IDE)

Sun NetBeans – www.sun.com (Free - search for NetBeans)

Eclipse – www.eclipse.org (a free open source IDE)

Build and Deployment Issues Selecting the best help format 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.

Selecting the best help format

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.

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

Platforms

Browsers

Minimum versions required by your product

Help Formats Commonly used help formats: HTML Help 1.x WebHelp / Web Help WinHelp – Not in Vista but… Uncommonly used help formats: HTML Help 2.0 (used with Microsoft VisualStudio.NET) JavaHelp Vista help – Not available to us in Vista

Commonly used help formats:

HTML Help 1.x

WebHelp / Web Help

WinHelp – Not in Vista but…

Uncommonly used help formats:

HTML Help 2.0 (used with Microsoft VisualStudio.NET)

JavaHelp

Vista help – Not available to us in Vista

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

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

Sample Context ID Mapping for HTML Help Sample .h file entry: #define IntroTopic 0001 #define CloseSpeech_PM 2001 #define EngineTerminated_E 3001 Sample .ali file entry: IntroTopic=Intro_Topic.htm CloseSpeech_PM=CloseSpeech_Method.htm EngineTerminated_E=EngineTerminated_Event.htm

Sample .h file entry: #define IntroTopic 0001 #define CloseSpeech_PM 2001 #define EngineTerminated_E 3001

Sample .ali file entry: IntroTopic=Intro_Topic.htm CloseSpeech_PM=CloseSpeech_Method.htm EngineTerminated_E=EngineTerminated_Event.htm

Help Authoring Tools (HATs) RoboHelp – www.adobe.com Flare – www.madcapsoftware.com * Doc-to-Help – www.componentone.com * Help & Manual – www.ec-software.com/ WebWorks ePublisherPro – www.quadralay.com AuthorIT – www.authorit.com For a searchable database of HATs, see hat-matrix.com/ - Char James-Tanny’s service * Demo CDs available

RoboHelp – www.adobe.com

Flare – www.madcapsoftware.com *

Doc-to-Help – www.componentone.com *

Help & Manual – www.ec-software.com/

WebWorks ePublisherPro – www.quadralay.com

AuthorIT – www.authorit.com

For a searchable database of HATs, see hat-matrix.com/ - Char James-Tanny’s service

* Demo CDs available

Advanced Text Editors NoteTab Pro and EditPad Pro: Both tools have: Spell-checking. Big plus if you work in a mixed OS environment: Neither tool inserts Windows-style line feed characters in Unix files. NoteTab Pro has an auto-complete option for html tags and other languages. Has a free version with reduced functionality. www.notetab.com $19.95, Lots of other tools here. EditPad Pro has color-coding for custom html tags www.jgsoft.com $39. Free full-featured (except for Spell Check) evaluation download available. JG Soft has other tools such as a PowerGrep tool, Registry editor, and others.

NoteTab Pro and EditPad Pro:

Both tools have: Spell-checking. Big plus if you work in a mixed OS environment: Neither tool inserts Windows-style line feed characters in Unix files.

NoteTab Pro has an auto-complete option for html tags and other languages. Has a free version with reduced functionality. www.notetab.com $19.95, Lots of other tools here.

EditPad Pro has color-coding for custom html tags www.jgsoft.com $39. Free full-featured (except for Spell Check) evaluation download available. JG Soft has other tools such as a PowerGrep tool, Registry editor, and others.

Uses for EditPad Pro Very good for adding / revising text in source code files (C, Java, and C#) Auto indent / tab Spell-checking color-coding for custom html tags Auto-sorting Specifying line length per file type

Very good for adding / revising text in source code files (C, Java, and C#)

Auto indent / tab

Spell-checking

color-coding for custom html tags

Auto-sorting

Specifying line length per file type

Uses for NoteTab Pro Very good for adding HTML / XML tags to text copied to source code files from other file formats HTML wizard – auto-create Apply HTML / XML coding to text via wizard Spell-checking

Very good for adding HTML / XML tags to text copied to source code files from other file formats

HTML wizard – auto-create

Apply HTML / XML coding to text via wizard

Spell-checking

File / Folder Level Comparison (Differencing Tools) Beyond Compare – Performs folder and file level comparisons, ASCII and binary. Can detect that ASCII or binary files are different but can only show the differences in ASCII files, not binary files. Highlights the specific characters different between 2 ASCII files. Has a 30-day full-featured free trial. www.scootersoftware.com/ Retail price: $30 Araxis Merge - Performs folder and file level comparisons, ASCII and binary. Has a 30-day free trial. www.araxis.com/merge/index.htm l Retail price: $129

Beyond Compare – Performs folder and file level comparisons, ASCII and binary. Can detect that ASCII or binary files are different but can only show the differences in ASCII files, not binary files. Highlights the specific characters different between 2 ASCII files. Has a 30-day full-featured free trial. www.scootersoftware.com/ Retail price: $30

Araxis Merge - Performs folder and file level comparisons, ASCII and binary. Has a 30-day free trial. www.araxis.com/merge/index.htm l Retail price: $129

Search and Replace Tool Funduc – Searches & replaces both folders and zip files. Will search & replace ASCII and binary files. Will search binary files but cannot replace by itself. Has plug-ins for Word, Excel, and PowerPoint. http://www.funduc.com $25 Many other tools here also. FAR (Find and Replace) – Search and replace tool, help decompiler / comparison tool. Two month free trial http://www.helpware.net/FAR/ Cost: buyer’s choice

Funduc – Searches & replaces both folders and zip files. Will search & replace ASCII and binary files. Will search binary files but cannot replace by itself. Has plug-ins for Word, Excel, and PowerPoint. http://www.funduc.com $25 Many other tools here also.

FAR (Find and Replace) – Search and replace tool, help decompiler / comparison tool. Two month free trial http://www.helpware.net/FAR/ Cost: buyer’s choice

Sample APIs Google APIs – code.google.com/more/#label=APIs&product=gdata Google Earth API – earth.google.com/comapi/ Google Maps API – code.google.com/apis/maps/ BackPack – www.backpackit.com/

Google APIs – code.google.com/more/#label=APIs&product=gdata

Google Earth API – earth.google.com/comapi/

Google Maps API – code.google.com/apis/maps/

BackPack – www.backpackit.com/

Breaking into this Market Get training to develop the skills: - Courses - Self-paced training - On-the-job training Make your own sample help systems, with context-sensitive help coded Write some sample programs

Get training to develop the skills: - Courses - Self-paced training - On-the-job training

Make your own sample help systems, with context-sensitive help coded

Write some sample programs

Education / Training Opportunities Programming courses at local colleges STC conferences / workshops

Programming courses at local colleges

STC conferences / workshops

Self-Paced Training Manuel Gordon’s API materials ( www.gordonandgordon.com ) Documenting APIs: Writing Developer Documentation for Java APIs / SDKs – James Bisso / Victoria Maki ( 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

Manuel Gordon’s API materials ( www.gordonandgordon.com )

Documenting APIs: Writing Developer Documentation for Java APIs / SDKs – James Bisso / Victoria Maki ( 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

Other Resources MSDN – msdn.microsoft.com RoboWizard Web site – www.robowizard.com Flare forums – www.madcapsoftware.com RoboHelp / Flare Web site – www.grainge.org/

MSDN – msdn.microsoft.com

RoboWizard Web site – www.robowizard.com

Flare forums – www.madcapsoftware.com

RoboHelp / Flare Web site – www.grainge.org/

Listservers (Yahoo Groups) STC API – groups.yahoo.com/group/svcstcapi/ API writers – groups.yahoo.com/group/APIWriters/ NetTechWriters – groups.yahoo.com/group/nettechwriters/ HATT – groups.yahoo.com/group/HATT/

STC API – groups.yahoo.com/group/svcstcapi/

API writers – groups.yahoo.com/group/APIWriters/

NetTechWriters – groups.yahoo.com/group/nettechwriters/

HATT – groups.yahoo.com/group/HATT/

Listservers (Yahoo Groups), cont. MSHelp 2.0 – groups.yahoo.com/group/MSHelp2/ Eclipse – groups.yahoo.com/group/eclipse_tw/

MSHelp 2.0 – groups.yahoo.com/group/MSHelp2/

Eclipse – groups.yahoo.com/group/eclipse_tw/

Web Services – A Growing Area Web Service - An application that provides a Web API to perform application integration Platform / language independent Related to service oriented architectures (SOAs) Uses SOAP (Simple Object Access Protocol) to send / receive XML messages

Web Service - An application that provides a Web API to perform application integration

Platform / language independent

Related to service oriented architectures (SOAs)

Uses SOAP (Simple Object Access Protocol) to send / receive XML messages

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

Web Services A Manager’s Guide – Anne Thomas Mannes

Service Oriented Architecture for Dummies – Judith Hurwitz, Robin Bloor, and Carol Baroudi

Typical Daily Activities Check nightly build logs for failures / checkins Update SVN Research any changes to APIs, error messages, etc. Check bug system for my assigned bugs, changes to bugs I’m following, new API-related bugs Download & install new kits (if it’s safe to do so) Document new features / changes to APIs

Check nightly build logs for failures / checkins

Update SVN

Research any changes to APIs, error messages, etc.

Check bug system for my assigned bugs, changes to bugs I’m following, new API-related bugs

Download & install new kits (if it’s safe to do so)

Document new features / changes to APIs

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

Description of APIs / SDKs

Benefits to writers

Drawbacks to writers

Training

Writing considerations (tools, formats, issues for context-sensitive help)

Closing Thank you. Questions? Ed Marshall Marshall Documentation Consulting [email_address] www.MarshallDocumentationServices +1 978-339-3095

Thank you.

Questions?

Ed Marshall

Marshall Documentation Consulting

[email_address]

www.MarshallDocumentationServices

+1 978-339-3095