API Documentation Tool Comparison
•
0 likes•62 views
API Documentation Tool Comparison for companies to choose readily available HATs without depending on DevOps for customization. Disclaimer: All the information in these slides are based on the requirements
Recommended
Recommended
More Related Content
Similar to API Documentation Tool Comparison
Similar to API Documentation Tool Comparison (20)
More from Raghuram Pandurangan
More from Raghuram Pandurangan (17)
Recently uploaded
Recently uploaded (20)
API Documentation Tool Comparison
- 1. Doc. Tools Comparison for API Integration Docs. - Raghuram Pandurangan
- 2. Objective of this exercise We performed this exercise to evaluate few Authoring tools that are currently available in the market and shortlisted four of them that provide industry standard API doc output and suits our requirement. What is a Help Authoring Tool? A Help authoring tools is a software that assists technical writers to create, manage, and publish product documentatio. Few examples of HATs are Readme, Document360, Madcap flair, Redocly, Paligo, etc.
- 3. Current Tech Stack of PayU India Devguide • WordPress for Authoring • React JS for FE [Output] Limitations with the Current Authoring Tool • API Test Calls on the Devguide is not possible in current implementation • Too much dependency on Engineering & UI/UX team for WP customization • Takes much time for developing UI for API Docs & Playground for Test Calls • May require dedicated engineering team to develop and maintain the Devguide platform.
- 4. Mandatory Features to look for in an Authoring Tool • Minimal learning curve while adopting the new Help Authoring Tool (HAT) • Ease of migration of old content to the new HAT • Supports migration of existing WP Content • Cloud-based HATs must be robust and stable • Stitched experience of API guides and API Playground on the same platform • Easy to embed videos and other medias • Staging environment for easier reviews • Supports versioning of APIs • Native Search on doc portal Good to Have Features • Custom JavaScript • Private Hub login via SSO/oAuth
- 5. List of Compared Tools • Developerhub.io • ReadMe (most preferred tool for producing API docs ) • Redocly • Stoplight (best suited for API designing) • Paligo
- 6. Comparison Summary Features DeveloperHub.io (Enterprise) ReadMe (Business Plan) Stoplight Paligo Redocly Help Authoring Tool Yes Yes Yes Yes Yes 3-Pane layout (API ref) Yes Yes Yes Yes Yes Stitched Exp. (Dev Guide + Test Calls) Yes (with API Reference) Yes (Incomplete as there is a new tab / window needed) No No No iFrame Yes Yes Yes Yes No Info. Embed Custom JavaScript Yes No [Enterprise Plan only] No No No Info. Code Walkthrough No (expected after 3-4 months) Recipes (1 eg.) No No No
- 7. Comparison Summary [Contd.] Features DeveloperHub.io (Enterprise) ReadMe (Business Plan) Stoplight Paligo Redocly Changelogs No Yes No No No Analytics Yes Yes Yes Yes Yes Developer Feedback Yes Yes No. Of API logs Not supported $100/month (Addon) No No No Suggest Edits [Dev] Yes Yes No No No Staging Env. No No No No [ Enterprise only] No Pricing/project (Business) $544/project with 4 users $399/month $319/month $440/month $300/month
- 8. Comparison Summary [Contd.] Features DeveloperHub.io (Enterprise) ReadMe (Business Plan) Stoplight Paligo Redocly Writer-Friendly Yes [Markdown Editor] Yes [Markdown Editor] No Yes [HTML] No Login using PayU Account (JWT) Yes Yes (Dev. Effort Needed – need to discuss with CO) No No No UI Customization Yes Limited and Needs Dev No Info Using CSS No Info Effort to add new APIs to Playground Import OAS 3.0 standard API collection or manual Import Postman/Swa gger (as per OAS standards) collec tion Import Postman/S wagger as per OAS standa rds Manually include code samples Import Postman/Swag ger as per OAS standards
- 9. Comparison Summary [Contd.] Features DeveloperHub.i o (Enterprise) ReadMe (Business Plan) Stoplight Paligo Redocly API Downtime Alerts No Info Yes No Info No Info No Info Community Discussions No Yes No No No Content Interchange Markdown Markdown XML XML DITA XML Programming Languages autogenerated for API calls 45 languages 45 languages 40 languages No Info. 11 languages Migration of Content Markdown File Import by Content team [2-3] or Support can do it [Costs may be involved ] Markdown File Import Manual for PayU [2-3 months by Content team] Markdown Fil e Import Yes No Info.
- 10. Developerhub.io
- 12. Landing Page
- 14. ReadMe
- 18. Recipes [Code Walkthrough]-ReadMe Use Cases: • Very useful for Code Walkthrough of SDKs and Integrations • Can be used as an in- platform sample app • Supports multiple languages.
- 19. Community Discussions-ReadMe https://docs.readme.com/main/docs/discussion-forums Enhanced dev- exp by leveraging dev interactions
- 20. Automatic Syncing with API Def.-ReadMe
- 21. Doc Metrics-ReadMe • Comprehensive dashboard view of metrics per day/week monthly/Quarterly/yearly basis: • Page Views • API calls (5M for Business tier) • Top used Endpoints • New Users activity • Page View • First API call • API errors • Page Quality
- 24. Stoplight
- 25. Stoplight • Regular API Docs output (similar to Postman) • Works only with Std. API Definitions (GitHub, OpenAPI, PostMan, etc.) Not user-friendly or adding API docs takes time • Downside • Unable to start with Manual API Definition • Sample: • Calendly (API Docs.) • Fiserv (Case study)
- 27. Paligo • Good CCMS for content reuse (Single Sourcing) • Integration with several Enterprise products • Content import wizard • Multichannel Publishing • Samples • Moogsoft
- 28. Redocly • Regular API Docs output • Works only with Std. API Definitions (GitHub, OpenAPI, PostMan, etc.) - Hardstop • Not writer-friendly or adding API docs takes time • Samples
Editor's Notes
- Code without context is just code. That's why most docs include clarifications and summaries—so the reader can understand the practical applications of the code, and what their program will be able to do once the software is integrated. But including these explanations and summaries isn't enough. They have to be accessible only when and where your readers need them. Paypal's original documentation site had two panes. But since its navigation bar was not dynamic, readers lost their navigation menu—and context—as they scrolled down the page. That's why critics of this documentation say that “the structure of the documentation is a catastrophe [...] The descriptions of how to set things up have no links to the APIs and the APIs are not linked to examples.” Clearbit does this by putting dynamic nav bars in the left pane, explanations in the middle, and sample code on the right. Putting all the info together means that devs can see how everything works in context faster, and start trying their hand at the code sooner. A three-pane view lets the user curate their own experience. It doesn't prioritize explanations over sample code (or vice versa). Whether you want to be briefed in plain English or to skim the sample code, a three-pane view puts all relevant info in one place and lets the user adjust as needed. There's only so much real-estate on your screen. Letting readers curate their own experiences means they can choose what to look at, without you risking decisions that may limit your audience. Let Readers Make Calls with an API Explorer The #1 thing your API doc readers want is to see what your API is capable of—and the best way to do that is by giving them a chance to try it themselves. Adding in an API Explorer lets you engage people of all technical backgrounds to make some of the most common calls in a few seconds, and without leaving your site. Quickstarts that let you create a developer sandbox are incredibly popular, but, they too come with some friction. Docusign requires the reader to first go to a separate page to create a (free) Sandbox account, verify their email, set up a password, and then they can set up their API key.