이번에는 What Factors Contribute to Good API Documentation? 이라는 글입니다.
테크니컬 라이터가 활동할 수 있는 시장은 점점 작아지고 그 틈새 시장으로 API 라는 것이 떠오르고 있다는 것을 알았다면. 이제는 좋은 API 문서가 어떤 것인지 알고 자신의 경쟁력을 높이라는 의미겠죠.
단순히 문서 교정자로서 참여하는 것이 아니라 API 기획 단계에서 참여하는 것을 전제로 합니다. API Design 이라는 표현을 사용하고 있네요.
예를 들어 설명하는 내용은 아래와 같습니다.
...Similarly, using a delete method for all three object types is consistent, but if you instead used “remove” for cars and boats, and “delete” for trucks, the developer user would likely become confused. And you, as the technical writer, would observe that what could be a nicely organized
structure is, in fact, confusing...
웹사이트 기획에서도 강조하는 부분인데 일관성 있는 표현을 사용해야 한다는 겁니다. 같은 작업을 처리하는 기능인데 어디서는 remove라고 쓰고 다른 곳에서는 delete라고 쓴다면 사용자가 혼란스러울 수 있다는 거죠.
...As with any other software documentation, audience analysis is key to determining what to say and how to present it in your API documentation...
그리고 또 한가지는 용어가 기능을 적절하게 설명해주어야 합니다. 그냥 귀찮다고 print1, print2 이렇게 표시해버리면 사용자가 print1과 print2가 어떤 차이가 있는지 직관적으로 알 수 없겠죠.
좋은 API를 만들기 위해서는 이미 만들어진 좋은 API를 찾아봐야 한다는 조언도 반복해서 던져주고 있습니다. 페이스북이라든지 플리커, Django, NPR 서비스를 참고하고 자신에게 필요한 것이 어떤 것인지 찾아보라고 하네요.
http://www.django-rest-framework.org/
https://developers.facebook.com/docs/
https://www.flickr.com/services/
http://www.npr.org/api/widgets.php
마지막으로 6가지 결론을 내면서 마무리합니다.
- A clear statement of the API’s purpose
- Automatically generated documentation for easy reference
- Good code snippets and good code samples
- Quickstart documents and tutorials (such as a “Hello, World!” tutorial)
- Searchable and navigable documentation
- Awareness and understanding of relevant programming concepts
앞에서 언급하지 못했던 것이 있는데 API를 멋지게 관리할 수 있는 도구로 swagger를 추천해주었습니다.
https://helloreverb.com/developers/swagger
관련된 내용을 찾아보다가 outsider 님이 남기신 글을 보았는데 swagger 보다는 I/O docs라는 것을 추천하시는군요.
I/O Docs를 사용한 API 문서화
http://blog.outsider.ne.kr/990
...별로 써보진 않았지만 Swagger는 문서화를 자동화로 만들어주는데 이런 자동화를 위해서 Swagger쪽에 좀 코딩을 해야한다. 모델등을 만들어야 하는데 이게 실제 서비스의 모델과 중복이라서 관리가 만만치 않아보였고(이부분을 자동화해주는 도구가 좀 있기는 하다) 문서화를 위한 작업으로는 너무 비대해 보였다...
코드 조각이나 샘플을 만드는 것은 어떻게 보면 쉬울 수 있지만 바로 적용 가능하고 이해하기 쉬운 코드를 만들어야 한다는 점에서 상당히 어려운 요구사항입니다.
