요즘 살짝 관심있는 분야라 흥미롭게 읽다가 한 문장에서 딱 마음이 걸렸습니다.
...API 레퍼런스는 이를 사용하는 개발자가 가장 많이 보는 기술 문서이며, 문서 엔지니어링을 어떻게 하느냐에 따라 작성 시간 및 출력물 모양이 크게 달라진다. 이런 이유로 전문 테크니컬 라이팅팀을 보유한 회사라면 자체 API 문서화 솔루션을 가져야 한다고 생각한다. 완전히 새로운 도구를 만들어야 한다는 것이 아니라, 이미 있는 도구를 사용하더라도 트렌드 변화에 맞춰 정확하게 전문적인 결과물을 내놓는 프로세스를 가지고 있어야 한다는 뜻이다. 구글도 그렇고 마이크로소프트도 그렇다. LINE 역시 다르지 않다...
최근 오프라인으로만 제공하던 API 레퍼런스 게시를 처리하면서 몇몇 회사들을 조사해보았는데, 글쓴이가 이야기한것처럼 구글이나 LINE은 그런데, 흥미롭게도 NAVER에서 JavaDoc 형식을 그대로 게시하는 걸 보고, 아 NAVER도 이렇게 하는데 우리는 뭘 ^^ 이라고 생각했던 것을 반성해봅니다. 시간이 된다면 이 문서를 기반으로 좀 더 고민해봐야겠습니다.
SIGDOC의 조사 결과는 상당히 흥미롭습니다. 원문은 아래 링크입니다.
http://sigdoc.acm.org/cdq/how-developers-use-api-documentation-an-observation-study/
How Developers Use API Documentation: An Observation Study - Special Interest Group on Design of Communication
by Michael Meng, Stephanie Steinhardt, and Andreas Schubert ABSTRACT Application Programming Interfaces (APIs) play a crucial role in modern software engineering. However, learning to use a new API often is a challenge for developers. In order to support t
sigdoc.acm.org
이 연구는 개발자 인터뷰가 아니라 관찰을 기반으로 진행했습니다. 이전 유사한 연구들이 인터뷰나 설문을 통해 진행됐는데, 실제 그들의 이야기가 행동과 일치하지 않는다는 것을 발견했다고 합니다. 뭐 다른 분야도 마찬가지겠지만요.
...For example, Lethbridge, Singer, & Forward (2003) noted that the software engineers who participated in their study claimed to spend approximately 40% of their time reading documentation. However, the observation results showed that only 3% of the logged events over the entire observation period were in fact related to documentation...
이 글은 리뷰보다는 나중에 실제 적용을 해보는 것이 더 중요할 듯 합니다.
* 마소 기사와 살짝 다르긴 하지만, 내용은 거의 같은 글이 LINE 엔지니어링 블로그에 올라와 있습니다.
https://engineering.linecorp.com/ko/blog/document-engineering-api-documentation/
문서 엔지니어링과 API 문서화 - LINE ENGINEERING
테크니컬 라이터(technical writer)라는 말을 들으면 대부분 '라이터'라는 단어만 보고 '글 쓰는 사람'이라 생각하기 십상입니다. 물론 틀린 것은 아니지만, 실상 키보드를 두드리며 글 쓰는 일이 테크니컬 라이터 업무의 대부분을 차지하지는 않습니다. 하루에 얼마 동안 글을 쓰는지 측정해 본 적은 없으나, 테크니컬 라이터 톰 존슨(Tom Johnson)이 말하기로는 일하는 시간의 약 10%라고 합니다. 그렇다면 그 밖의 시간에는 뭘 할까요? 역시
engineering.linecorp.com
* 이 링크도 같이 참고
API Documentation: The Secret to a Great API Developer Experience
Today, organizations across all industries are recognizing the business and strategic opportunities of investing in an API program. APIs enable digital transformation, and open the doors to a host of engineering and business possibilities. But the growth
swagger.io
