APIs And SDKs Breaking Into And Succeeding In A Specialty Market
-
Upload
bill-dubie -
Category
Technology
-
view
5 -
download
2
description
Transcript of APIs And SDKs Breaking Into And Succeeding In A Specialty Market
APIs and SDKs: Breaking Into and Succeeding in a Specialty
Market
Ed Marshall
Copyright 2009
1
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
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
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
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.
7
Key Programming Concepts
• Data types / variables
• Program control – loops, conditions, etc.
• Logical operators
• Data structures such as arrays
• Functions / methods
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 / test examples, talk / write in gibberish
• Work more closely with developers
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
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
11
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
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
13
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
14
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 - *
15
What Code Files Do You Need?
C:• .c files• header files (.h files)• other files: error filesJava:• .java filesC++• .cpp files• Header files (.h files)C#:• .cs files
16
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
17
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
18
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
19
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#latests
rc – current version is 1.5.8 (Dec. 08)
20
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
21
Possible Strategies / Timeline for Accessing Code
1. Edit comments in code but don’t make changes in code – shows you know the difference between comments & 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.
22
Templates
• Show and discuss a typical template containing the sections / information that should be included for each function.
23
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
24
Microsoft IDEs
• Visual C
• Visual C#
• Visual Basic
• Visual J#
All free from http://www.microsoft.com/express/download/
25
Other IDEs
• Sun NetBeans – www.sun.com (Free - search for NetBeans)
• Eclipse – www.eclipse.org (a free open source IDE)
26
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.
27
Determining Which Help Format to Use
• Platforms
• Browsers
• Minimum versions required by your product
28
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
29
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 product30
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.htmEngineTerminated_E=EngineTerminated_Event.htm
31
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
32
Advanced Text EditorsNoteTab 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 feedcharacters 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 tagswww.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.
33
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
34
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
35
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.html
Retail price: $129
36
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
37
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/
38
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
39
Education / Training Opportunities
• Programming courses at local colleges
• STC conferences / workshops
40
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
41
Other Resources
• MSDN – msdn.microsoft.com
• RoboWizard Web site – www.robowizard.com
• Flare forums – www.madcapsoftware.com
• RoboHelp / Flare Web site – www.grainge.org/
42
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/
43
Listservers (Yahoo Groups), cont.
• MSHelp 2.0 – groups.yahoo.com/group/MSHelp2/
• Eclipse – groups.yahoo.com/group/eclipse_tw/
44
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
45
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
46
Typical Daily Activities
1. Check nightly build logs for failures / checkins
2. Update SVN
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 & install new kits (if it’s safe to do so)
6. Document new features / changes to APIs
47
Summary
• Description of APIs / SDKs
• Benefits to writers
• Drawbacks to writers
• Training
• Writing considerations (tools, formats, issues for context-sensitive help)
48
Closing
• Thank you.• Questions?
Ed Marshall
Marshall Documentation [email protected]
www.MarshallDocumentationServices+1 978-339-3095
49