Dec 3 rd, 2004STC 6 th Annual Conference API Documentation Trends and Opportunities Rajeev Jain

Dec 3 rd, 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 3 rd, 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 3 rd, 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 3 rd, 2004 Rajeev Jain Who should write? Developers or SMEs? Technical Writers? Both?

Dec 3 rd, 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 3 rd, 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 3 rd, 2004 Rajeev Jain API document includes… Class name, object name, or method Parent class Inheritance Exceptions Associations or dependencies Standards conformance

Dec 3 rd, 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 3 rd, 2004 Rajeev Jain Auto-generation tools Doxygen Javadoc Mif2man (man pages) Txt2Man (man pages)

Dec 3 rd, 2004 Rajeev Jain Other tools MS Word FrameMaker PageMaker Adobe Acrobat HTML editors

Dec 3 rd, 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 3 rd, 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 3 rd, 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 3 rd, 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 3 rd, 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 3 rd, 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 3 rd, 2004 Rajeev Jain Special Thanks Bhasker VP Engineering Clovis Solutions Inc. L. Amott Technical Writer