Talks
Speakers
Events
Topics
Sign in
Home
Talks
Speakers
Events
Topics
Leaderboard
Use
Analytics
Sign in
Suggest modification to this talk
Title
Description
RailsConf 2018: Automating Empathy: Test Your Docs with Swagger and Apivore by Ariel Caplan Ugh, documentation. It's the afterthought of every system, scrambled together in the final days before launch, updated sparingly, generally out of date. What if we could programmatically verify that our API documentation was accurate? What if this helped us build more intuitive APIs by putting our users first? What if documentation came first, and helped us write our code? With Swagger and Apivore as our weapons of choice, we'll write documentation that will make your APIs better, your clients more satisfied, and you happier.
Date
Summarized using AI?
If this talk's summary was generated by AI, please check this box. A "Summarized using AI" badge will be displayed in the summary tab to indicate that the summary was generated using AI.
Show "Summarized using AI" badge on summary page
Summary
Markdown supported
In the talk titled "Automating Empathy: Test Your Docs with Swagger and Apivore" presented by Ariel Caplan at RailsConf 2018, the importance of effective API documentation is emphasized. Caplan addresses the common disdain developers have for documentation, highlighting the challenges of maintaining accurate and user-friendly docs. **Key Points Discussed:** - **Documentation Challenges**: Caplan begins with a discussion on the universal struggle developers face with documentation, portraying it as an afterthought that often leads to frustration. - **Human Error vs. Complexity**: Acknowledging that human error is a constant, Caplan argues that the inherent complexity of modern APIs contributes significantly to documentation challenges. He stresses the need for tools that reduce the cognitive load on developers. - **Shifting Perspective**: Rather than viewing documentation as a chore, Caplan encourages developers to adopt a "documentation first" approach, arguing that when documentation drives development, it improves both the coding process and user satisfaction. - **Tools for Improvement**: Caplan introduces Swagger (OpenAPI Specification) for creating readable API documentation and Apivore for testing that the documentation aligns with actual code behavior. These tools help ensure that APIs are not only well-documented but also that they function as expected. - **Implementation Process**: The talk outlines a structured approach to API development, advocating for: - Writing documentation as the first step for new endpoints. - Using tests that verify endpoints against documentation, thus ensuring both accuracy and completeness. - **Case Study**: Caplan shares his experience implementing Swagger and Apivore in a healthcare system, noting that it resulted in a significant cleanup in their codebase and improved the overall quality of their API. The project saw a net reduction of over 2,700 lines of code while adding 1,800 lines of new, high-quality code. **Conclusions and Takeaways:** - API documentation is not just a necessity but can serve as a tool for better development practices that lead to improved user satisfaction and software quality. - The traditional view of documentation as a secondary task is flawed; when treated as a primary focus, it can alleviate many common pitfalls of API development. - By using tools like Swagger and Apivore, developers can explore a more streamlined and effective workflow, ultimately enhancing the user experience by ensuring accurate and comprehensible documentation.
Suggest modifications
Cancel
