Topics

What’s an API?
API Documentation:
Needs of an expert audience
How to Explain so Experts will Understand
Essential API concepts

Organization of API documentation
David Wernick
AlmondWeb Ltd.
tel 02-5712246
david@almondweb.com
http://www.almondweb.com

Copyright © 2003 AlmondWeb Ltd. All rights reserved.

2

What's an API? Interfaces are for Everyone

Set objGraph = New ColumnChart
objGraph.Background = “Cyan”
objGraph.Foreground = “LightBlue” Programming
Interface

API = Application Programming Interface objGraph.XAxis.Scale.Lower = 0
...
objGraph.Show

The way applications talk to each other User
Interface

The way developers talk to applications

Configuration
Interface
3 4

1
Typical Documentation Set Topics

User Interface
What’s an API?

– User’s Guide

Needs of an expert audience
– Getting Started

Configuration Interface
Essential API concepts
– Installation Guide
Organization of API documentation
– Administrator’s Guide

Programming Interface
– Programmer’s Guide
– API Reference

5 6

Audience for API Documentation How to Peel a Potato (Novice Version)

Software developers To peel the potatoes, follow this procedure:

Assumed knowledge:
– What an application does (probably)
– How to use the application (probably)
– How to program (definitely)
– How to program in a particular language (maybe)

Assumed lack of knowledge:
– How to program the application
– Why to program the application
1. Grasp a potato in your left hand.
2. Hold the peeler or knife in your right hand.
3. Moving the peeler in short, quick motions,
scrape the peel from the potato and expose
the white.
4. Repeat steps 1-3 for all the other potatoes.

7 8

2
How to Peel a Potato (Expert Version) Reader's Perspective
One of the most nutritious parts of a potato is the
peel. The peel is rich in vitamin B and other nutrients, Novice version Expert version
and it is also the most flavorful part of the potato.
Many people like to eat the peel, and if you're one of Procedural Conceptual
them, you can cook with unpeeled potatoes.
Imperative Advisory
It's true, though, that the peel looks ugly to our
Western eyes, and some people don't like the taste. Less prior knowledge More prior knowledge
Often, too, the peel is dirty and hard to clean. If you
prefer to peel your potatoes, follow this procedure:
1. Grasp the peeler and potato in your hands.
2. Scrape the peel from the potato and expose the
white.

9 10

Reader’s Perspective (cont.) Author's Perspective

Novice version Expert version

The novice version doesn't meet the
expert's needs
Author may be an expert, but Author may be a novice, but

The expert version may not meet the must think like a novice must become an expert
novice's needs
– Exception: novices who want to become Author should not explain Author cannot explain what
what the reader cannot the author does not
experts understand understand

11 12

3
How to Become an API Expert Topics

Learn to program
What’s an API?

Learn programming concepts
Needs of an expert audience

Read programming manuals
Essential API concepts

Ask questions
Organization of API documentation

Practice ...

13 14

Object-Oriented Programming Objects

Object-oriented
– Visual Basic
– C++

Everything is an object
– Java
Objects have:
– JavaScript
– Properties
– ASP
– COM – Methods
– XML

Not object-oriented
– C
– COBOL
– FORTRAN
– WebWorks macro language

15 16

4
Object Model for Fixing Your Car Car Object
Property Data type Example of property value

Car
Model String “Studebaker”
Owner
Garage Year Integer 1957
Boss
Mechanic Km Long Integer 752,821

Problems Array of Problems(0) = “Hood pops

String open when close trunk”
Problems(1) = “Trunk pops
open when close hood”

17 18

Garage Object Fixing Your Car in Visual Basic

Declare variables
Dim objCar As Car

Method Dim objGarage As Garage
FixCar Dim lngPrice As Long
Create Car object
Set objCar = New Car

Syntax objCar.Model = “Studebaker”
Function FixCar(objCar As Car) As Long objCar.Problems(0) = _
“Hood opens when close trunk”
Parameter Return value ...
Create Garage obj
Set objGarage = New Garage
lngPrice = objGarage.FixCar(objCar)
objCar.Owner.Pay(lngPrice, objGarage)

Call methods
19 20

5
Example: a Word Macro Fixing Your Car in XML
Method
Public Sub FindSelectedText()
<FixCar> Car object
Declare variables <Car>
Dim objRange As Range
Dim strText As String <Model>Studebaker</Model>
Create Range obj <Problems>
Set objRange = Selection.Range <Problem>Hood opens when close trunk</Problem>
strText = objRange.Text ...
Call objRange.Collapse(wdCollapseEnd) </Problems>
objRange.Find.Text = strText </Car> Garage object
... <Garage>
objRange.Find.Execute <Name>Jake’s Studebaker</Name>
If objRange.Find.Found Then objRange.Select </Garage>
</FixCar>
End Sub Call methods

21 22

Topics Conceptual Documentation

Programmer’s Guide or Developer’s Guide

What’s an API?
Introduction
– What you can do with the API

Needs of an expert audience – System architecture
– Operating principles

Essential API concepts

Tutorial

Organization of API documentation – “Hello, World” program

Concepts
– Object model
– Programming guidelines

How to ...
– Code examples
– Advanced configurations (registry, cfg files, network)
– Application design examples

23 24

6
Language of Examples API Reference

Most systems can be programmed in
Object-model documentation

multiple languages
Online help
– Visual Basic / Visual C++ / ASP
One help topic per object

Typically one help topic per property or

Examples are often in a single language method
– Visual Basic

25 26

Object Property
Topic Topic

Copyright © Copyright ©
ClickSoftware, Inc. ClickSoftware, Inc.
Used with permission. Used with permission.

27 28

7
 Method
Topic

API Documentation:
How to Explain so Experts will Understand

David Wernick
Copyright ©
ClickSoftware, Inc. AlmondWeb Ltd.
Used with permission.
tel 02-5712246
david@almondweb.com
http://www.almondweb.com

Copyright © 2003 AlmondWeb Ltd. All rights reserved.

29