Embed Size (px)
Citation preview
Dec 3rd, 2004 STC 6th Annual Conference
API DocumentationTrends and Opportunities
Rajeev [email protected]@clovissolutions.com
Dec 3rd, 2004 Rajeev Jain
Topics What is an API? When is an API required? Who uses it?
What info is required? Who should write API documents? What skills do you need? What tools do you need? Why auto-generation tools are not enough? What are current trends and challenges? What are the opportunities available?
Dec 3rd, 2004 Rajeev Jain
An API is… Application Programming Interface (API) A basic library of program coding classes
and related methods for building a software application
An interface through which user interacts with your software
Helpful in customization of software as per the needs
Without any GUI or user friendly interface
Dec 3rd, 2004 Rajeev Jain
Need of an API… An API is required by users who use code
to manipulate an application For example:
You don’t need an API to use FrameMaker, but you do need one if you want to change in how Frame works
You don’t need an API to use MS Word, but you do need one if you create complex macros in Word
Dec 3rd, 2004 Rajeev Jain
Who should write? Developers or SMEs? Technical Writers? Both?
Dec 3rd, 2004 Rajeev Jain
The audience Companies who want to make the
application work with their existing infrastructure and operating system
Companies that need to customize the software for their specific needs
Developers need it so that they can use the application to its full potential
Dec 3rd, 2004 Rajeev Jain
API document includes… Depending on the application, an API will
include some of the following: Syntax Description Parameters Return Values Calling Sequence Usage Example
contd…
Dec 3rd, 2004 Rajeev Jain
API document includes…
Class name, object name, or method Parent class Inheritance Exceptions Associations or dependencies Standards conformance
Dec 3rd, 2004 Rajeev Jain
Skills required Basic understanding of languages like C,
C++, Java, VB.NET, etc. Basic understanding of object-oriented
programming concepts Ability to understand code, functions,
methods, classes, etc. Ability to think as programmer Ability to interview SMEs
Dec 3rd, 2004 Rajeev Jain
Auto-generation tools
Doxygen Javadoc Mif2man (man pages) Txt2Man (man pages)
Dec 3rd, 2004 Rajeev Jain
Other tools
MS Word FrameMaker PageMaker Adobe Acrobat HTML editors
Dec 3rd, 2004 Rajeev Jain
Auto-generation tools
Used with source files Actual writing is done by
developers Helpful in freezing the content as
per the template Language inconsistency No direct contribution from TWs Does not provide great look and
feel options
Dec 3rd, 2004 Rajeev Jain
Current trends APIs are mostly written by SMEs and
developers Dependency on SMEs and developers for
the contents SMEs and developers do not have much
time to review the technical documents TWs don’t get an opportunity to work
with APIs TWs perform the editing, designing, flow,
and presentation related tasks
Dec 3rd, 2004 Rajeev Jain
API Documentation Process
Design template Get inputs from SMEs Organize information Send doc to SMEs for technical
accuracy review Send doc to be tested Submit doc for review Convert to PDF or HTML
Dec 3rd, 2004 Rajeev Jain
Opportunities
API documentation on rise due to shift towards product development
Most developers are not good writers
Exposure to programming world Writers with programming skills will
be in demand Above all - Higher salaries $$$
Dec 3rd, 2004 Rajeev Jain
Challenges
Update ourselves with basic programming skills
Developers with good writing skills may switch to this field
TWs with domain experience will be in demand
Dec 3rd, 2004 Rajeev Jain
Summary New field for Indian TWs Understand the basic programming
concepts Learn the basics of at least one
programming language Learn tools like Doxygen, JavaDoc,
Help2Man, Mif2man, Text2man Good News: Salary at par with
developers and may be more $$$
Dec 3rd, 2004 Rajeev Jain
Special Thanks Bhasker
VP EngineeringClovis Solutions [email protected]
L. AmottTechnical Writer
