Ruby Video

Title

Description

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 presentation titled "Let there be docs!" at the Friendly.rb 2023 conference, Svyatoslav Kryukov humorously discusses the often-overlooked topic of API documentation. He starts by acknowledging the challenges developers face with documentation, emphasizing its perception as a tedious task. He outlines the historical context of API development, mentioning the evolution from REST to various protocols like GraphQL, while noting the ongoing relevance of REST due to its flexibility.

Key points discussed include:

- **Issues with Documentation**: Kryukov reviews common frustrations, such as outdated documents leading to endless API questions, cumbersome manual testing setups, and frequent API updates causing frontend breakage.
- **The Role of AI**: He playfully questions the potential of AI to eliminate documentation efforts, providing a fictitious example that humorously illustrates the pitfalls of relying solely on automated tools.
- **Documentation Approaches**: The talk categorizes four key documentation strategies:
  - **Manual Documentation**: Straightforward but often outdated and poorly synced with current implementations.
  - **DSL-Based Documentation**: Ties documentation creation to code implementation, though it often leads to cluttered code and lacks test capabilities.
  - **Test-First Approach**: Documentation generated from tests ensures accuracy, though it is still a retrospective process.
  - **Documentation-First Approach**: This proactive approach emphasizes creating documentation before implementation or testing, enabling better team collaboration and earlier feedback. Kryukov argues this is the most effective method.
- **OpenAPI Specification**: Demonstrating the documentation-first concept, he introduces OpenAPI as a standardized format to create API specifications, and utilizes a fun example involving animal feeds to illustrate the specification process.
- **Tools and Collaboration**: He discusses tools like Swagger Editor, Spectral, and Schuma that facilitate the development and validation of OpenAPI documents, stressing the importance of collaboration across teams, including feedback loops.
- **Iterative Workflow**: The benefits of working through iterations, gathering feedback early, and adapting documentation to clarify understanding are emphasized.

Kryukov concludes by underscoring the importance of adopting a documentation-first approach to foster collaboration and clarity among development teams. He encourages attendees to experiment with these practices and tools, hoping they return to their workplaces inspired to elevate documentation efforts. With the memorable call to action, "Let there be docs!", he advocates for a shift in mindset towards valuing and prioritizing documentation in software development.

Suggest modification to this talk