DevOps Friendly Doc Publishing for APIs & Microservices

on YouTube ↗33m

" summary

An internal doc pipeline called Pub Hub is built and used at Cisco to normalize Swagger/OpenAPI, RAML and Markdown into a consistent site, driven from GitHub and integrated into CI/CD with staging and previewers. It accepts multiple inputs, uses open-source processors, supports localization, and provides both continuous deploy and approval workflows. Teams report saved time, more engineer-authored docs, and easier internal-to-external publishing, while remaining work includes linting, aging metrics and measuring adoption across developers and writers.

AI-written summary · about

" chapters (15)

1. 0:00Intro
2. 2:33API Developer Experience
3. 3:06App Dynamics
4. 4:37API Reference Docs
5. 5:23How are people doing this
6. 7:10Problems
7. 8:23API Reference
8. 9:42Initial Ideas
9. 12:09Project Overview
10. 13:18Project Setup
11. 14:31Samples
12. 15:08Feedback
13. 22:58Recommended resources
14. 23:41Cisco DevNet
15. 27:55Automation

" related talks

• 40mThe Rocky Road to DocOpsChris Noonan · Write the Docs Prague 2020
• 19mStreamlining API Documentation: Proven DocOps StrategiesKateryna Osadchenko · apidays London 2023
• 35mBuilding Docs like Code: Continuous Integration for DocumentationMason Egger · PyCon US 2020
• 12mAnne Gentle, Cisco DevNet | DevNet Create 2019Anne Gentle · Cisco DevNet Create 2019
• 26mA sensible API Document Management guideVanjikumaran Sivajothy · Apidays LIVE Paris 2020
• 36mBuilding Docs like Code: Continuous Integration for DocumentationMason Egger · PyCon Latam 2019
• 44mPushing documentation (so it doesn't hurt anymore)Markus Schlichting · Voxxed Days Ticino 2023
• 23mTreating Documentation like Code: a Practical AccountJodie Putrino · Write the Docs 2017