APIs and SDKs: Breaking Into and Succeeding in a Specialty Market
-
Upload
scott-abel -
Category
Technology
-
view
3.343 -
download
2
description
Transcript of APIs and SDKs: Breaking Into and Succeeding in a Specialty Market
![Page 1: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/1.jpg)
APIs and SDKs: Breaking Into and Succeeding in a Specialty Market
Ed Marshall
Copyright 2008
![Page 2: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/2.jpg)
APIs and SDKs
API = Application Programming InterfaceSDK = Software Development Kit
• Typical users and why they use them• Typical producers of these products• Examples
![Page 3: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/3.jpg)
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
![Page 4: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/4.jpg)
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
![Page 5: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/5.jpg)
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
![Page 6: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/6.jpg)
Reference Information for APIs
• Brief description• Syntax• Examples, examples, examples!• Error messages• Cross-references
![Page 7: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/7.jpg)
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.
![Page 8: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/8.jpg)
Key Programming Concepts
• Data types / variables• Program control – loops, conditions, etc.• Logical operators• Data structures such as arrays• Functions / methods
![Page 9: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/9.jpg)
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
![Page 10: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/10.jpg)
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
![Page 11: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/11.jpg)
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
![Page 12: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/12.jpg)
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
![Page 13: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/13.jpg)
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
![Page 14: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/14.jpg)
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.
![Page 15: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/15.jpg)
Determining Which Help Format to Use
• Platforms • Browsers• Minimum versions required by your product
![Page 16: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/16.jpg)
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
![Page 17: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/17.jpg)
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
![Page 18: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/18.jpg)
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.htmCloseSpeech_PM=CloseSpeech_Method.htmEngineTerminated_E=EngineTerminated_Event.htm
![Page 19: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/19.jpg)
Automated Tools
• Doxygen • JavaDoc• Sandcastle – New tool for .Net help (MSDN
style). Doc-to-Help supports Sandcastle help.• Others
![Page 20: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/20.jpg)
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
![Page 21: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/21.jpg)
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
![Page 22: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/22.jpg)
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.comFor a searchable database of HATs, see hat-
matrix.com/ - Char James-Tanny’s service
![Page 23: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/23.jpg)
Microsoft IDEs
• Visual Studio 2008 Visual C++• Visual C #• Visual Basic
All free from http://www.microsoft.com/express/download/
![Page 24: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/24.jpg)
Other IDEs
• Sun NetBeans – www.sun.com (Free - search for NetBeans)
• Eclipse – www.eclipse.org (a free open source IDE)
![Page 25: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/25.jpg)
Advanced Text EditorsNoteTabPro and EditPadPro:
• 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.
• 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 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.
![Page 26: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/26.jpg)
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
![Page 27: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/27.jpg)
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.
![Page 28: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/28.jpg)
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/
![Page 29: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/29.jpg)
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
![Page 30: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/30.jpg)
Education / Training Opportunities
• Programming courses at local colleges• STC conferences / workshops
![Page 31: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/31.jpg)
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
![Page 32: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/32.jpg)
Other Resources
• MSDN – msdn.microsoft.com• RoboWizard Web site – www.robowizard.com • Flare forums – www.madcapsoftware.com• RoboHelp / Flare Web site – www.grainge.org/
![Page 33: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/33.jpg)
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/
![Page 34: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/34.jpg)
Listservers (Yahoo Groups), cont.
• MSHelp 2.0 –groups.yahoo.com/group/MSHelp2/
• Eclipse – groups.yahoo.com/group/eclipse_tw/
![Page 35: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/35.jpg)
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
![Page 36: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/36.jpg)
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
![Page 37: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/37.jpg)
Summary
• Description of APIs / SDKs • Benefits to writers• Drawbacks to writers• Training• Writing considerations (tools, formats, issues
for context-sensitive help)
![Page 38: APIs and SDKs: Breaking Into and Succeeding in a Specialty Market](https://reader031.fdocuments.us/reader031/viewer/2022022404/54593a91b1af9fb66e8b57e8/html5/thumbnails/38.jpg)
Closing• Thank you.• Questions?
Ed Marshall
Marshall Documentation [email protected]
www.MarshallDocumentationServices+1 978-339-3095