Uwana Ikaiddi는 BigCommerce라는 온라인 커머스 회사에서 Developer Documentation Manager로 일하고 있습니다. 여기도 외부 파트너사에게 API를 제공하고 이에 대한 문서를 작업하고 있습니다.
API The Docs 2020 행사는 WTD 컨퍼런스와 다르게 컨퍼런스 일정이 오프라인처럼 정해져있지 않고 특정 기간 동안 순차적으로 영상을 공개하는 방식을 취하고 있습니다. 작년에는 4월부터 6월까지 시즌 1, 그리고 9월부터 11월까지 시즌 2였습니다. 시즌 1 영상 중 일부 전에 본 것을 제외하고 못 본 영상들만 정리하고 있습니다.
WTD 컨퍼런스와 다르게 Q&A는 따로 없습니다. 진행자도 없구요. 라이브로 진행을 하긴 하는데, 발표 내용에 Q&A를 따로 정리하지는 않습니다. 그래서 WTD는 보통 20분 강연에 10분 Q&A인데, 이곳은 30-40분 분량 강연이 진행됩니다.
그리고 2-3개 세션을 모아서 Q&A를 팟캐스트로 별도 제공합니다.
개발자 문서란?
이전에는 레퍼런스 문서 중심으로 작성했는데 최근에는 개발자 포털 같은 서비스를 제공하면서 개발자 경험에 좀 더 신경을 쓰고 새로운 API에 온보딩하는데 어려움이 없도록 신경쓰고 있다고 합니다. 물론 서비스하는 제품에 따라 다르겠지만 API 문서를 제공하는 곳이라면 비슷하지 않을까 싶네요.
개발자 문서의 독자는?
아래 내부 피드백을 얻는 방법에서도 설명하고 있지만, 내부 사용자가 좀 더 쉽게 피드백을 얻을 수 있습니다.
보통 외부 고객(사용자)를 생각하는데, 내부 사용자(개발자)도 같은 문서를 참조할 수 있습니다. 또한 기술지원팀에서도 고객 답변(안내)를 위해 문서를 활용할 수 있습니다. 그 외에도 마케팅팀이나 세일즈 조직에서도 문서를 사용합니다.
내부 피드백을 얻는 방법?
내부 피드백 뿐 아니라 개발이 진행되는 동안 테크니컬 라이터가 소외되지 않고 개발 과정에 참여하고 리소스를 얻기 위한 방법입니다. 특히 애자일 개발 조직에서 개발 주기를 따라가지 못한다면 문서가 개발에 방해가 될 수도 있습니다.
- 공개된 채널에 공개적으로 피드백을 달라고 요청하기(이 부분은 회사 문화가 어느 정도 뒷받침해주어야 합니다. 팀마다 독립적으로 일하고 다른 팀과 커뮤니케이션을 하는 문화가 아니라면 쉽지 않거든요).
- 개발팀 미팅에 참여해도 되냐고 요청하기 (대부분 개발팀에서는 구현된 내용이 문서에 잘 반영되기를 원하기 때문에 환영할 것이라고 합니다만 역시 회사마다 다를겁니다).
- 슬랙 같은 도구를 사용한다면 문서화에 대해 이야기할 수 있는 채널을 만들기
- JIRA 같은 이슈 관리 도구를 사용한다면 문서화에 대한 프로젝트 또는 라벨을 만들기
외부 피드백을 얻는 방법?
내부 사용자와 다르게 접근하기가 쉽지 않음(누가 사용하고 있는지조차 알기 쉽지 않습니다).
- 대안으로 페르소나를 활용할 수 있음(문서 일관성을 유지하기 위한 도구). 페르소나는 문서팀 뿐 아니라 개발자 애드보케이트, 교육, 마케팅팀 등에서 같이 사용할 수 있음
- 피드백을 받는 공개적인 창구를 만든다면 단일 창구로 시작하는 것이 좋음(깃헙 이슈, 요청 양식, 별점). 그리고 여유가 생기면 다양한 채널(슬랙, 트위터 등)으로 피드백 채널을 확장
피드백 반영은 어떻게?
- 피드백의 성격에 따라 대응(부족한 정보, 오래된 정보, 추가 예제)
- 피드백을 추적해 특정 주제에 대한 피드백을 분석
- 문서가 변경되면 변경 이력을 공지할 것. 소셜 미디어나 블로그, 이메일 레터 등을 통해 전달하는 것도 괜찮음
https://pronovix.com/event/api-docs-virtual-2020/uwana-ikaiddi
https://www.slideshare.net/APItheDocs/improving-developer-documentation
