Tag Archives: API documentation

주석 분석기를 이용한 간단한 API 문서화 방법

테크니컬 라이터로서 가장 재미있는 순간은 바로 새로운 프로젝트를 시작할 때입니다. 프로젝트를 시작하는 순간에는 모든 것이 열려 있어 자유로우며, 그 자유가 새로운 도메인에 대한 탐구심을 자극하기 때문입니다. 그런 점에서 짧지만 굵게 새로운 것을 시도하고 배울 수 있는 기술 문서 컨설팅은 제게 참 신나는 업무입니다. 이번 글에서는 몇 달 전에 진행했던 API 문서화 컨설팅에서 배운 내용을 공유하려 합니다. 주제는 새로운 언어를 위한 소스 코드 주석 기반 API 문서화 도구 만들기입니다. 정확히 말하면 ‘도구 만들기’라기보다 ‘도구 찾아 적용하기’이므로, 코딩이 많이 필요할 거라는 기대 혹은 염려는 가슴 한편에 고이 접어둬도 좋습니다.

문서 엔지니어링과 API 문서화

테크니컬 라이터(technical writer)라는 말을 들으면 대부분 ‘라이터’라는 단어만 보고 ‘글 쓰는 사람’이라 생각하기 십상입니다. 물론 틀린 것은 아니지만, 실상 키보드를 두드리며 글 쓰는 일이 테크니컬 라이터 업무의 대부분을 차지하지는 않습니다. 하루에 얼마 동안 글을 쓰는지 측정해 본 적은 없으나, 테크니컬 라이터 톰 존슨(Tom Johnson)이 말하기로는 일하는 시간의 약 10%라고 합니다.

그렇다면 그 밖의 시간에는 뭘 할까요? 역시 톰 존슨에 따르면 개발자 인터뷰, 다른 사람이 쓴 문서 리뷰, 앱 스크린 캐스팅이 필요할 때 아이폰 탈옥, 미디어위키에서 링크된 이미지에 캡션 넣는 방법 찾기 등등이라고 합니다. 그중에서도 제가 말하고자 하는 일은 비록 ‘아이폰 탈옥’ 같은 건 아니지만 결과적으로는 글쓰기와는 전혀 관계 없어 보이는 엔지니어링에 관한 것입니다.