Rachael Stavchansky는 Netlify Documentation Team Manager입니다.
네트리파이(Netlify)는 정적 웹사이트 호스팅을 제공하는 서비스입니다. 깃허브 페이지를 많이 사용하고 있지만 네트리파이도 여러 장점 때문에 많은 프로젝트에서 사용하고 있습니다.
Shuffle ball change: Sashay your way to clearer API documentation
API 문서화가 시장에서 주목받고 있는 건 아무래도 수요가 계속 늘어나기 때문입니다.
API 시장이 커지면서 개발자도 많아지고 작성해야 할 문서의 범위도 늘어나죠.
API 자체를 직관적으로 만드는 것도 중요하지만, 실제 사용에 있어서 문서가 같이 제공되지 않는다면 활용하는데 어려움이 따르게 됩니다. 그렇기 때문에 API 문서화 시장은 계속 늘어날 거구요.
API 문서화는 제품이나 서비스에 대한 이해를 기반으로 하지만 큰 틀은 다르지 않기 때문에 한번 들어오면 다른 곳으로 옮겨갈 때도 유리하게 작용할 수 있습니다.
발표에서는 4가지 케이스를 예로 들어서 설명하고 있는데요.
첫 번째 케이스는 이미 일관성 있는 문서를 가지고 있는 여러 서비스에 대해서 어떻게 대처할 것인가입니다.
이런 경우에는 권장하지 않지만 전체 내용을 엑셀 시트로 정리해서 분석하고 수정한 후 일괄적으로 반영했다고 하네요. 그 이후에 점진적으로 문서의 일관성을 개선하는 방향을 잡았다고 합니다.
나머지 케이스는 살짝 비슷했던 것 같은데, 일단 넘어가구요.
네트리파이에서는 개발자들이 참고할 수 있는 가이드라인을 작성했다고 합니다. 스타일 가이드처럼 복잡하지는 않고 딱 개발자가 작성할 부분에 대해 간략한 가이드와 해야 하는 것, 하지 말아야 하는 것만 정리했습니다.
예를 들어 반환 값에 대한 요약문이면 "Return"으로 시작하고 너무 구체적이지 않고 뭐 그런 내용입니다.
문법이니 맞춤법이니 뭐 그런 거는 없고 한눈에 딱 들어오게 해당 항목 작성을 위한 중요한 가이드만 제시하고 있습니다.
그리고 내용은 코드 내 주석으로 작성되는데, 코드 커밋 시 특정 태그를 달면 문서팀이 리뷰어로 지정됩니다. 그럼 리뷰 단계에서 적절하게 내용이 작성되었는지 코멘트를 달아준다고 합니다. 가이드를 기준으로 이런 이런 것들이 잘못 작성되었다 뭐 이런 식으로 말이죠.
이렇게 하면 문서팀에서 할 일이 많아질 것 같지만, 어느 정도 안정화 단계에 들어가면 개발자들이 알아서 문서에 대한 리뷰도 진행해준다고 합니다. 그럼 문서팀에서는 좋아요 정도만 남겨주는~
발표 슬라이드는 http://slides.com/rstav 에서 확인할 수 있습니다.
