API The Docs 2020 - API와 개발자 경험

Lorna Mitchell은 통신 서비스를 제공하는 보네이지(Vonage)의 DR팀 담당자입니다. 좋은 API라도 문서가 없다면 개발자들이 이를 사용하는데 어려움을 겪는다는 이야기입니다. 좋은 API 문서 또는 환경을 만들기 위해 어떤 것이 필요한지 설명하고 있습니다.

 

개발자들이 문서나 기능을 살펴볼 때 모든 항목을 한 번에 보지는 않습니다. 발표자는 이런 모습을 식당에서 메뉴판을 보고 주문하는 것이 비유했는데요. 특별한 경우가 아니면 모든 메뉴를 주문하지는 않는 모습과 비슷하다고 합니다. 때문에 문서를 만들 때는 적절한 분류를 통해 개발자가 원하는 항목을 선택할 수 있도록 해야 합니다. 메뉴판에 기재된 문서(음식)은 부족함이 없어야 합니다(마치 식당에 갔는데 메뉴마다 너무 편차가 심한 경우에는 좋은 식당이라고 인정을 받지 못하죠. 그래서 백종원의 골목식당을 보면 너무 산만한 메뉴는 최소한 다룰 수 있는 수준으로 간결하게 하라고 합니다).

Every API is someone’s first API. So don’t be afraid to over-explain things. 라는 메시지가 인상적이네요. 간결한 설명도 중요하지만 누군가 처음 사용하는 사용자를 위해 부족함은 없어야 한다는~

 

추가적인 요약 정리는 아래 내용을 참고하세요.

https://pronovix.com/event/api-docs-virtual-2020/lorna-jane-mitchell

Lorna Jane Mitchell - Beyond the API Reference: Developer Experience for APIs