CONTINUOUS REST API DOCUMENTATION DEVELOPMENT AND DELIVERY ABHISHEK

ABOUT THE SPEAKERS ▪ Abhishek Sura ▪ ▪ Manager, Information Development, Oracle Fusion Applications Responsible for design, development, and delivery of REST API documentation for Oracle Sales Cloud ▪ Vijay Tiwary ▪ ▪ Senior Manager, Information Development, Oracle Fusion Applications Responsible for the design, development, and delivery of developer documentation for the following Oracle Cloud Services: ▪ ▪ Oracle Sales Cloud Oracle Field Service Cloud SRM Oracle Knowledge © 2016, STC INDIA CHAPTER 2

AGENDA ▪ ▪ Introductions ▪ Q&A Discuss an ideal approach for continuous REST API

KEY OBJECTIVES ▪ ▪ Appreciate REST APIs, continuous delivery, and related concepts ▪ ▪ ▪ Apply the Pareto Principle while scoping developer documentation Understand how to provide documentation support during continuous development and delivery Understand the importance of code checkpoints Apply kaizen to continuously improve quality © 2016, STC INDIA CHAPTER 4

REST APIs: A RECAP ▪ APIs are an alternative way of interacting with an application. ▪ REST APIs let you develop custom applications and integrate your application with external applications. ▪ REST is particularly useful for smaller computing devices such as mobile and PDAs. © 2016, STC INDIA CHAPTER 5

REST API DOCUMENTATION: AN OVERVIEW REST API documentation contains what you need to know in order to use a RESTful API. INCLUDES Resource Descriptions Attribute Descriptions Method Descriptions Possible Responses Sample Code © 2016, STC INDIA CHAPTER TOOLS Swagger Spring RAML Confluence Postman, and the Advanced REST Client OUTPUT HTML e. PUB PDF 6

AN INTRODUCTION TO CONTINUOUS DELIVERY (CD) Continuous delivery is a software approach where teams ensure that every change to the system is release-ready. Automates delivery © 2016, STC INDIA CHAPTER Improves productivity Fixes bugs quicker Improves customer satisfaction 7

CD: THE RATIONALE We are on CLOUD! Build © 2016, STC INDIA CHAPTER Test

ent of • the Use quality content checks and its to log structur code e, line based change on s at continu critical ously stages evolvin of the g develo standar pment ds and process guidelin • to Support es. • multiple Prioritiz ensure e items release that are s docum likely to simulta entatio give the neously n and maxim and code um ROI. ensure line are that synchr change onous. s to the code translat e to docum entatio n, © 2016, STC INDIA CHAPTER Continuous Improvement Quality Checks Documentatio n Scoping Parallel Development Cycles CD PROCESS PRIMER 9

PROVIDING DOC SUPPORT FOR PARALLEL DEVELOPMENT CYCLES © 2016, STC INDIA CHAPTER 10

DOCUMENTATION SCOPING: IDEAL SCOPE • There is A LOT to document! • So, how do you select what to document?

DOCUMENTATION SCOPING: FOLLOWING PARETO Apply the Pareto (80/20 rule) principle for scoping and prioritizing items that maximize ROI. Attributes Finders Parameters Time 80% Result s Effor t 20% Understand that scope ultimately affects quality and costs. 80% Examples Use Cases © 2016, STC INDIA CHAPTER Quality Scope. Resource 20% 12

DOCUMENTATION SCOPING: INCREMENTAL LAYERED APPROACH While scoping you may follow the following incremental layered approach: 1. Harvested reference documentation 2. Static Getting Started documentation 3. Reusable payloads and code snippets 4. Developer Network (Web sites, Forums, etc. ) 5. Dynamic instance-specific auto-generated documentation that can take customization into account

ITERATIVE QUALITY CHECKS © 2016, STC INDIA CHAPTER 14

CONTINUOUS QUALITY IMPROVEMENT ▪ Apply the Kaizen philosophy: “Change for better” © 2016, STC

CONTINUOUS QUALITY IMPROVEMENT ▪ Machine readable API Catalogs ▪ Automated documentation processes: ➢Content creation and review in the source ➢Processes for auto generation of reference content ➢Automated content review and quality control ➢Automated testing of code samples and example payloads ▪ On-demand, self-publishing ▪ Searchable content hosting © 2016, STC INDIA CHAPTER 16

DOES IT WORK? RESUL TS © 2016, STC INDIA CHAPTER Significant decrease Scope improvement in known issues release to release Large decrease in time for release to market Error resolution time down to a minimum 17