Your SlideShare is downloading. ×
0
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
APIs and SDKs: Breaking into and Succeeding in a Specialty Market
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

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

211

Published on

Ed Marshall

Ed Marshall

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

  • Be the first to like this

No Downloads
Views
Total Views
211
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
2
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. APIs and SDKs: Breaking Intoand Succeeding in a SpecialtyMarketEd Marshall2007 STC - Philadelphia Metro ConferenceCopyright 2007
  • 2. APIs and SDKsAPI = Application Programming InterfaceSDK = Software Development Kit• Typical users and why they use them• Typical producers of these products• Examples
  • 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 administrators guides• User configuration guides
  • 4. Ideal Information for SDKs• Provide an overview of the SDK• Describe the tools and components in the SDKand how they relate to the APIs• Describe each tool in detail• Describe any sample programs included in theSDK
  • 5. Ideal Information for APIs• Break each component into the variousfamilies• Describe each API completely, including cross-references to any types used in the definition• Provide and explain examples that show bothtrivial and complex use of the class / API
  • 6. Reference Information for APIs• Brief description• Syntax• Examples, examples, examples!• Error messages• Cross-references
  • 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’sGuide, etc.
  • 8. Key Programming Concepts• Data types / variables• Program control – loops, conditions, etc.• Logical operators
  • 9. Benefits to the Writer• Do more advanced technical writing:Higher payHigher status• Good if you like to play with software at thecode level, create / test examples, talk / writein gibberish• Work more closely with developers
  • 10. Drawbacks to the Writer• Possibly restrictive / repetitive writing• Possibly less contact with users as they aredevelopers / programmers themselves• Possibly, more technically challengingdevelopment / build environments
  • 11. Knowledge / Personality Traits thatWork Well• Some knowledge of programming languagesBUT you don’t have to be a programmer!• Willingness to work with advanced /programmer types of tools – Use softwareinstead of specs• Desire to work at the code level and write fordevelopers who work at the code level
  • 12. Knowledge / Personality Traits, cont.• Willingness / confidence to work closely withsenior developers• Ability to develop context-sensitive level help ata lower-level than typical end-user (window-level) help
  • 13. Breaking into this Market• Get training to develop the skills:- Courses- Self-paced training- On-the-job training• Make your own sample help systems, withcontext-sensitive help coded• Write some sample programs
  • 14. Education / Training Opportunities• Programming courses at local colleges• STC conferences / workshops
  • 15. Self-Paced Training• Manuel Gordon’s API materials (www.gordonandgordon.com)• Documenting APIs: Writing DeveloperDocumentation for Java APIs / SDKs – JamesBisso / Victoria Maki (www.bitzone.com/book.html)• Deitel & Deitel “(C / C++ / C# / Java) How toProgram”• Sams “Teach Yourself…”• Sample projects, such as the HTML Help API
  • 16. Other Resources• MSDN – msdn.microsoft.com• RoboWizard Web site – www.robowizard.com• Flare forums – www.madcapsoftware.com• RoboHelp / Flare Web site – www.grainge.org/
  • 17. Listservers (Yahoo Groups)• STC API – http://groups.yahoo.com/group/svcstcapi/• API writers –http://groups.yahoo.com/group/APIWriters/• NetTechWriters –http://groups.yahoo.com/group/nettechwriters/• HATT – http://groups.yahoo.com/group/HATT/
  • 18. Listservers (Yahoo Groups), cont.• MSHelp 2.0 –http://groups.yahoo.com/group/MSHelp2/• Eclipse –http://groups.yahoo.com/group/eclipse_tw/
  • 19. Ways to Get Information• Reading the specifications• Using the software• Attending demos• Running automated tools against the software• Providing fill-in-the-blank templates todevelopers
  • 20. Build and Deployment Issues• Use of automated build systems• Use of source code control systems• Other tools to do file comparisons, advancedtext editors, multi-file search and replace, etc.
  • 21. Automated Tools• JavaDoc• DOXYGEN• Others
  • 22. Help Authoring Tools• Flare• RoboHelp – It’s back, as of Jan. 2007• WebWorks ePublisherPro – for Frame / Word• Doc-to-Help• AuthorIT
  • 23. Advanced Text EditorsNoteTabPro and EditPadPro:• Both tools have: Spell-checking. Big plus if you work in a mixed OSenvironment: Neither tool inserts Windows-style line feedcharacters in Unix files.• NoteTabPro has an auto-complete option for html tags and otherlanguages.www.notetab.com $19.95, Lots of other tools here.• EditPadPro has color-coding for custom html tagswww.jgsoft.com $39.JG Soft has other tools too such as a PowerGrep tool, Registry editor, andothers.
  • 24. Search and Replace ToolFunduc: Will search & replace both folders andzip files. Will also search & replace ASCII andbinary files. Some cautions about using it withbinary files but my initial tests with Word .DOCfiles worked fine.www.funduc.com $25Many other tools here also.
  • 25. File / Folder Level Comparison(Differencing Tools)• Beyond Compare - Folder and file level comparisons, ASCII and binary.Can detect that ASCII or binary files are different but can only show thedifferences in ASCII files, not binary files. Highlights the specific charactersdifferent between 2 ASCII files.http://www.scootersoftware.com/Retail price: $30• Araxis Merge - Folder and file level comparisons, ASCII and binaryhttp://www.araxis.com/merge/index.htmlRetail price: $129
  • 26. Determining Which Help Format to Use• Platforms• Browsers• Minimum versions required by your product
  • 27. Common Help Formats• WinHelp – Not in Vista but…• HTMLHelp 1.x• HTMLHelp 2.0 (used with MicrosoftVisualStudio.NET)• WebHelp / Web Help• JavaHelp• Vista help – Not initially available to us in Vista
  • 28. Context-sensitive Help• Need to determine if it is necessary• Need developers to implement / hook to theAPI• Have to use the appropriate API for the helpformat• Mapping of context IDs to numbers / textstrings• Need to test all links from the product
  • 29. Sample Context ID Mapping forHTMLHelp• Sample .h file entry:// Properties and Methods#define CloseSpeech_PM 2001• Sample .ali file entry:CloseSpeech_PM=CloseSpeech_Method.htm
  • 30. Summary• Description of APIs / SDKs• Benefits to writers• Drawbacks to writers• Training• Writing considerations (i.e., tools, formats,issues for context-sensitive help)
  • 31. Closing• Thank you.• Questions?Ed Marshalled.marshall@verizon.net978-339-3095

×