OpenAPI를 사용하기로 했다면 다음 4가지 단계를 따르는 것을 권장합니다(물론 발표자의 개인적인 의견이므로 절대적인 것은 아닙니다).
1. 새로운 문서 만들기(New documentation)
일반적으로 OpenAPI 문서화를 처음 접하는 이들이 가장 어려워하는 부분입니다. 일반 문서로 작성된 내용을 컴파일할 수 있는 OpenAPI로 옮기는 부분이죠. 특히 테크니컬 라이팅에 익숙한 이들이 더 어려워합니다. 왜냐하면 OpenAPI는 테크니컬 라이팅보다는 코딩에 가깝기 때문이죠. 때문에 테크니컬 라이터처럼 생각하지 말고 개발자처럼 생각해야 합니다.
아래 이미지의 경우 accountValue라는 필드값이 필수인데 입력할 수 있는 문자 길이 범위는 0~50으로 초안이 작성되어 있습니다. 이 두가지 내용은 서로 모순되는 내용이죠. 문서화 과정에서 이런 점도 체크가 되어야 합니다.
간단한 OpenAPI를 다루는 것은 어렵지 않습니다. 하지만 복잡한 구조의 경우 문서를 렌더링하는 과정에서 오류가 생기면 이를 찾아내는 과정을 거쳐야 합니다. 일반적인 테크니컬 라이팅처럼 생각하고 작업 시간을 산정했을 때 문제가 될 수 있는 부분입니다. 생각보다 더 시간이 걸릴 수 있다는 것을 알아야 합니다.
많은 경우 테크니컬 라이터가 개발자의 지시를 받아 OpenAPI를 작성합니다. 개발자의 언어를 이해할 수 있다면 그럴 필요는 없고 테크니컬 라이터 스스로 OpenAPI를 작성할 수 있습니다.
2. 업데이트하기(Maintenance)
새로운 또는 변경된 사항에 대해 모두 업데이트를 해주어야 합니다. 실제 개발 프로세스 내에서 작업이 이루어지지 않으면 놓치는 부분이 많을 겁니다. 모든 기능 변경 PR에 대해서 OpenAPI 작성자가 관여하고 참여해야 합니다.
3. 프로토타이핑(Prototyping)
이 부분은 살짝 이해가 안되긴 하는데 개발 이전에 프로토타이핑을 만들어서 검증하는 과정에도 참여한다 뭐 이런 의미 같네요.
4. API First
이번 발표의 전제는 개발자와 테크니컬 라이터가 같은 OpenAPI 코드를 사용한다는 겁니다. 개발자가 코드를 작성하고 거기에서 추출한 정보로 문서화를 하는 것이 아니라는 것이죠. 수정이 필요할 때는 테크니컬 라이터는 설명(description) 부분만 수정하고 나머지는 개발자가 관리하는 형태로 가져갈 수 있습니다.
좀 더 자세한 이야기는 자신의 블로그를 참고하라고 합니다.
https://medium.com/codex/roberts-rules-of-order-for-api-documentation-writing-a2d52bfba41c
Q&A에서는 많은 테크니컬 라이터가 OpenAPI에 대한 두려움을 가지고 있는데 무엇이 문제일까요? 라는 질문이 있었구요. 그 답은 OpenAPI에 대해 접근할 때 자신이 개발자가 되어야 한다고 의식하기 때문이라고 합니다. 어떤 프로그래밍 언어를 배우고 접근해야 한다고 생각하는거죠. 개발자처럼 생각할 필요는 있지만 전문 개발자가 되어야 한다는 건 아닙니다. 필요한 부분만 그때 그때 익혀서 활용할 수 있습니다.
Redocly가 API 문서화에 있어서 강력한 지지를 받고 있는 이유는 깔끔한 인터페이스 때문이라고 생각한답니다. 사용자를 귀찮게 하지 않고 딱 필요한 작업을 바로 처리할 수 있게 지원하기 때문이죠.
API 문서만으로 충분한가에 대한 물음에는 API 문서(레퍼런스)는 사전과 같은 역할이라고 합니다. 최소한 필수적으로 제공되어야 하는 것이죠. 하지만 문법이나 사용방법 등을 생각하면 그에 따른 문서가 필요합니다.
https://youtu.be/6v5mHxgZGvk?si=nVAlcxdpZqP5Tzh7
