이번 글은 Lessons Learned as a Novice API Writer 라는 글인데 처음 API 분야에 뛰어드는 분들에게 조언이 되는 좋은 글이 많이 남겨져 있네요. 물론 API가 아니더라도 테크니컬 라이팅 분야에 종사하는 분들이라면 모두에게 해당하는 내용입니다.
특히 인상적인 내용은 아래 문구였습니다.
...I reviewed specifications and researched technologies used by the team so that I could ask better questions and save the team time by focusing on their current development efforts...
기술 분야에서 연구 인력 또는 개발자가 가이드를 작성하는데 있어서 문제가 되는 것 중 하나는 자신의 관점에서 글을 쓴다는 것입니다. 뭐 이정도는 알고 있겠지하고 넘어가버리면 어디서 빠지는 부분이 있는지 알 수 없습니다. 테크니컬 라이터가 이렇게 작성된 가이드를 받아서 정리하려고 할 때 기술을 제대로 이해하고 있지 않다면 어떤 부분에 문제가 있는지 알 수 없습니다. 좋은 질문을 할 수 없다는 것이지요.
또한 저자가 일하는 환경은 애자일 개발방법론을 채택하고 있습니다. 이런 환경에서 어떤 프로세스에 문제가 생긴다면 전체 프로세스가 제대로 흘러가지 못하겠죠.
아래 단락에서 마지막 문장의 like를 ~을 좋아한다라고 해석하니 문장이 이상하더군요. 음. 변태인가 싶은...
그래서 페이스북 개발자영어 Q&A에 질문을 남겼더니 ~을 좋아한다는 의미가 아니라 ~처럼 여기다의 의미라고 설명을 해주셨습니다.
https://www.facebook.com/groups/engfordevqa/permalink/782936435103965/
...Since our organization uses an Agile programming methodology, I made sure to add documentation tasks for the team during sprint planning. I was like gum on the
bottom of their shoes...
또 한가지 오해하기 쉬운 부분이 문서를 만들면 모든 개발자가 이것을 볼 것이라는 오해입니다. 개발자마다 자신의 스타일이 있고 필요에 따라 행동하게되죠.
I have also found that not all developers learn the same way. Some like to start by reviewing the code samples, while others might look over conceptual information or diagrams. In the end, while I found some great ideas by reviewing different API sites, I concluded that the best approach to documenting the API is what made sense for my organization and readers.
문서로 만들어지는 것 뿐 아니라 실제 코드 내 주석도 명확하게 표현해야 하는 이유가 여기에 있습니다. 라이브러리 코드 자체가 공개되는 경우에는 이런 부분도 주의해야겠죠. API 작성자가 코드에 관여하는 것은 좀 애매하긴 하지만~ API 문서를 만드는 단계에 따라서 API 작성자가 최종 코드를 받아서 내용을 교정하고 배포하는 것을 담당할 수도 있다고 봅니다.
