When documenting is designing
summary
Argues that technical writers step into API design by producing concrete artifacts: an API style guide, a collaborative design template and versioned OpenAPI specs hosted in Postman, plus running regular design reviews and office hours. Describes building a small React viewer that pulls Postman specs via Axios and renders them with Redoc/Swagger to spark conversations. Focuses on naming, meaningful error messages, linting and contract testing as measurable levers that reduce documentation churn and catch breaking changes early.
AI-written summary · about
chapters (24)
- 0:00Intro
- 0:24About me
- 0:58Core assumption
- 1:48Words happen everywhere
- 2:27Words also happen to be design
- 3:34API designs are made of words
- 4:36Because APIs enable conversations
- 5:55API design is about choosing the right words to enable systems to converse
- 6:20API design depends on how you build APIs
- 7:22The problem with code first APIs
- 7:50API First workflow
- 9:05API Design is nobody's a shared responsibility
- 9:55The API designer Technical writer overlap
- 11:11Why tech writers should bother
- 12:03Let's document error responses...
- 12:43Start with this simple question
- 13:28Advocate for API First
- 15:08Push for API Design Guidelines
- 18:20Own summaries and descriptions
- 19:435. Provide naming expertise
- 22:43Fight for meaningful error messages
- 23:287. Build an internal API Viewer
- 24:34Ingredients for a simple API viewer
- 25:27Resources
related talks
22mThe Art of Effective API Design
40mDocumentation as User Experience
29mHumanizing Your Documentation
27mAPI Design Through the Lens of Photography
33mCollaboration & Productivity-Missing Links in API Development
30mWhy Your New API Product Will Fail
43mDocumentation is UX! - Change my mind
46mDieter RAMs: the ten principles of good API design