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

              Copyright 2008
APIs and SDKs
API = Application Programming Interface
SDK = Software Development Kit

• Typical users and why they use the...
Typical Documentation Deliverables
•   Programmer’s reference guides
•   Online help (in some format, more later)
•   Prog...
Ideal Information for SDKs
• Provide an overview of the SDK
• Describe the tools and components in the SDK
  and how they ...
Ideal Information for APIs
• Break each component into the various
  families
• Describe each API completely, including cr...
Reference Information for APIs
•   Brief description
•   Syntax
•   Examples, examples, examples!
•   Error messages
•   C...
Examples of API / SDK Documentation

• Visual Basic ActiveX Control Help Sample –
  print and online help
• C++ API Help S...
Key Programming Concepts
•   Data types / variables
•   Program control – loops, conditions, etc.
•   Logical operators
• ...
Benefits to the Writer
• Do more advanced technical writing = Higher
  pay / higher status
• Good if you like to play with...
Drawbacks to the Writer
• Possibly restrictive / repetitive writing
• Possibly less contact with users as they are
  devel...
Knowledge / Personality Traits that
              Work Well
• Some knowledge of programming languages
  BUT you don’t have...
Knowledge / Personality Traits, cont.
• Willingness / confidence to work closely with
  senior developers
• Ability to dev...
Ways to Get Information
•   Read the specifications
•   Use the software
•   Attend demos
•   Run automated tools against ...
Build and Deployment Issues
• Use of automated build systems
• Use of source code control systems
• Other tools to do file...
Determining Which Help Format to Use
• Platforms
• Browsers
• Minimum versions required by your product
Common Help Formats
• WinHelp – Not in Vista but…
• HTMLHelp 1.x
• HTMLHelp 2.0 (used with Microsoft
  VisualStudio.NET)
•...
Context-sensitive Help
• Need to determine if it is necessary
• Need developers to implement / hook to the
  API
• Have to...
Sample Context ID Mapping for
             HTMLHelp
Sample .h file entry:
  #define IntroTopic 0001
  #define CloseSpeech_...
Automated Tools
• Doxygen
• JavaDoc
• Sandcastle – New tool for .Net help (MSDN
  style). Doc-to-Help supports Sandcastle ...
Doxygen
• Very powerful code generation tool
• Free
• Reads specially formatted comments in code
• Supports C / C++, Java,...
JavaDoc

• Powerful code generation tool for Java
• Free
• Reads specially formatted comments in code
• Outputs browser-ba...
Help Authoring Tools (HATs)
• Flare – www.madcapsoftware.com
• RoboHelp – www.adobe.com
• Help & Manual - www.ec-software....
Microsoft IDEs
• Visual Studio 2008 Visual C++
• Visual C #
• Visual Basic

All free from
  http://www.microsoft.com/expre...
Other IDEs
• Sun NetBeans – www.sun.com (Free - search
  for NetBeans)
• Eclipse – www.eclipse.org (a free open source
  I...
Advanced Text Editors
NoteTabPro and EditPadPro:

• Both tools have: Spell-checking. Big plus if you work in a mixed OS
  ...
File / Folder Level Comparison
               (Differencing Tools)
• Beyond Compare – Performs folder and file level compa...
Search and Replace Tool
Funduc – Searches & replaces both folders and
 zip files. Will search & replace ASCII and
 binary ...
Sample APIs
• Google APIs –
  code.google.com/more/#label=APIs&product=
  gdata
• Google Earth API – earth.google.com/coma...
Breaking into this Market
• Get training to develop the skills:
    - Courses
    - Self-paced training
    - On-the-job t...
Education / Training Opportunities
• Programming courses at local colleges
• STC conferences / workshops
Self-Paced Training
• Manuel Gordon’s API materials
  (www.gordonandgordon.com)
• Documenting APIs: Writing Developer
  Do...
Other Resources

•   MSDN – msdn.microsoft.com
•   RoboWizard Web site – www.robowizard.com
•   Flare forums – www.madcaps...
Listservers (Yahoo Groups)
• STC API – groups.yahoo.com/group/svcstcapi/
• API writers –
  groups.yahoo.com/group/APIWrite...
Listservers (Yahoo Groups), cont.
• MSHelp 2.0 –
  groups.yahoo.com/group/MSHelp2/
• Eclipse – groups.yahoo.com/group/ecli...
Web Services – A Growing Area
• Web Service - An application that provides a
  Web API to perform application integration
...
Web Services / SOA resources
• Web Services A Manager’s Guide – Anne Thomas
  Mannes
• Service Oriented Architecture for D...
Summary
•   Description of APIs / SDKs
•   Benefits to writers
•   Drawbacks to writers
•   Training
•   Writing considera...
Closing
• Thank you.
• Questions?

                  Ed Marshall

        Marshall Documentation Consulting
            ed...
Upcoming SlideShare
Loading in …5
×

APIs and SDKs: Breaking Into and Succeeding in a Specialty Market

2,057
-1

Published on

Presented by Edward Marshall at Documentation and Training East 2009, October 29 - November 1, 2008 in Burlington, MA.

Documenting Application Programming Interfaces (APIs) and Software Development Kits (SDKs) is a challenging but rewarding niche in technical communication. This session discusses what these products do, who uses them, moving into this area, benefits / drawbacks to working on these products, issues unique to these products, and commonly used help authoring tools. As the demand is often greater than the supply of writers, you can get higher pay than for other types of writing. You often get greater flexibility in telecommuting / working remotely in this area. Sample source code and the documentation produced from them will be shown.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
2,057
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
50
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

APIs and SDKs: Breaking Into and Succeeding in a Specialty Market

  1. 1. APIs and SDKs: Breaking Into and Succeeding in a Specialty Market Ed Marshall Copyright 2008
  2. 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
  3. 3. Typical Documentation Deliverables • Programmer’s reference guides • Online help (in some format, more later) • Programmer’s guides • Data dictionaries • API and SDK installation manuals • System administrator's guides • User configuration guides
  4. 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
  5. 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
  6. 6. Reference Information for APIs • Brief description • Syntax • Examples, examples, examples! • Error messages • Cross-references
  7. 7. 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.
  8. 8. Key Programming Concepts • Data types / variables • Program control – loops, conditions, etc. • Logical operators • Data structures such as arrays • Functions / methods
  9. 9. 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
  10. 10. 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
  11. 11. 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
  12. 12. 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
  13. 13. Ways to Get Information • Read the specifications • Use the software • Attend demos • Run automated tools against the software • Provide fill-in-the-blank templates to developers
  14. 14. 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.
  15. 15. Determining Which Help Format to Use • Platforms • Browsers • Minimum versions required by your product
  16. 16. Common Help Formats • WinHelp – Not in Vista but… • HTMLHelp 1.x • HTMLHelp 2.0 (used with Microsoft VisualStudio.NET) • WebHelp / Web Help • JavaHelp • Vista help – Not available to us in Vista
  17. 17. 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
  18. 18. Sample Context ID Mapping for HTMLHelp 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
  19. 19. Automated Tools • Doxygen • JavaDoc • Sandcastle – New tool for .Net help (MSDN style). Doc-to-Help supports Sandcastle help. • Others
  20. 20. Doxygen • Very powerful code generation tool • Free • Reads specially formatted comments in code • Supports C / C++, Java, (Corba and Microsoft) Java, Python, IDL, and C# • Outputs RTF, compiled HTML Help, browser-based help, and LaTex (PDF) • Active development / support • www.stack.nl/~dimitri/doxygen/download.html#latests rc – current version is 1.5.5
  21. 21. 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
  22. 22. Help Authoring Tools (HATs) • Flare – www.madcapsoftware.com • RoboHelp – www.adobe.com • Help & Manual - www.ec-software.com/ • WebWorks ePublisherPro – www.quadralay.com • Doc-to-Help – www.componentone.com • AuthorIT – www.authorit.com For a searchable database of HATs, see hat- matrix.com/ - Char James-Tanny’s service
  23. 23. Microsoft IDEs • Visual Studio 2008 Visual C++ • Visual C # • Visual Basic All free from http://www.microsoft.com/express/download/
  24. 24. Other IDEs • Sun NetBeans – www.sun.com (Free - search for NetBeans) • Eclipse – www.eclipse.org (a free open source IDE)
  25. 25. Advanced Text Editors NoteTabPro and EditPadPro: • 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. • NoteTabPro 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. • EditPadPro 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.
  26. 26. 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
  27. 27. 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. www.funduc.com $25 Many other tools here also.
  28. 28. 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/
  29. 29. 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
  30. 30. Education / Training Opportunities • Programming courses at local colleges • STC conferences / workshops
  31. 31. 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
  32. 32. Other Resources • MSDN – msdn.microsoft.com • RoboWizard Web site – www.robowizard.com • Flare forums – www.madcapsoftware.com • RoboHelp / Flare Web site – www.grainge.org/
  33. 33. 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/
  34. 34. Listservers (Yahoo Groups), cont. • MSHelp 2.0 – groups.yahoo.com/group/MSHelp2/ • Eclipse – groups.yahoo.com/group/eclipse_tw/
  35. 35. 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
  36. 36. 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
  37. 37. Summary • Description of APIs / SDKs • Benefits to writers • Drawbacks to writers • Training • Writing considerations (tools, formats, issues for context-sensitive help)
  38. 38. Closing • Thank you. • Questions? Ed Marshall Marshall Documentation Consulting ed.marshall@verizon.net www.MarshallDocumentationServices +1 978-339-3095

×