Dan은 엔지니어링 배경을 가지고 있으며 여러 분야에서 일을 하다가 지금은 소프트웨어 쪽에서 일하고 있고 문서 작성 특히 API 문서화 관련된 일을 하고 있습니다. API 문서화와 관련해서 다음과 같은 목표를 가지고 있습니다.
- 일관성: 누가 어디서 작성을 하든 조직 내 API 문서는 같은 형식으로 작성되고 배포되기를 원합니다.
특히 마이크로 서비스 아키텍처인 경우 각 서비스를 개발하는 조직이 달라지면서 일관성을 잃어버릴 수 있습니다.
- 명확성: 최신의 코드 정보를 API 문서가 담고 있어야 합니다. 틀린 내용이 없고 정확한 내용을 포함해야 합니다.
업데이트되지 않거나 오래된 문서에 대한 이야기는 다른 곳에서도 많이 들을 수 있는 이야기입니다.
개발팀과의 관계에 있어서 개발팀의 배포 기준에 문서화를 포함하지 않는 경우가 많습니다. 그래서 어느 정도 중요도를 서로 정하고 제품과 같이 문서를 배포할 것인지 아니면 제품 배포 후 일정 기간 내에 문서를 업데이트할 것인지 정하는 것도 좋은 방안이 될 수 있습니다. 그렇지 않으면 개발팀 입장에서는 문서화가 제품의 발목을 잡는다고 생각할 수 있거든요.
- 쉬운 유지 관리: 어렵지 않게 업데이트할 수 있어야 하며 누구나 쉽게 관리할 수 있어야 합니다.
특히 개발자 모두가 테크니컬 라이팅에 익숙하지는 않습니다. 사용자를 대상으로 하는 글쓰기는 더욱 그렇죠.
뭐 하여간 이런저런 문제를 해결하기 위해 두 가지 방안을 선택했다고 합니다.
- 점진적인 접근: 한 번에 뭔가 해결하려고 하지 않고 하나씩 문제를 해결했습니다.
- 사람들과 상호 작용하기: 프로세스 변화를 그냥 전달하는 것이 아니라 공감할 수 있게 접근했습니다.
제목에서 알 수 있듯이 Dan이 추구하는 것은 완전한 자동화는 아니고 어느 정도 사람이 개입하는 방식입니다. 자동화가 좋은 것 같아 보이지만 더 많은 시간을 잡아먹기도 하고 각 조직의 특성을 반영하기는 어렵다고 합니다. 그래서 프로세스를 사람이 직접 하나하나 튜닝(?)하면서 개선해 나가는 방식을 선택했다고 합니다. 커뮤니케이션에 좀 더 집중하고 자동화로 인한 갈등을 해소하는 것이죠.
제목만 보면 API 문서화 프로세스에 대한 이야기같지만 그것보다는 커뮤니케이션에 좀 더 집중된 세션이 아니었나 싶습니다.
중간에 버닝맨 축제 이야기가 나오는데 같은 것인지 모르겠으나 2022년 행사에서 Sarah Day가 라이트닝 토그로 버닝맨 축제 스태프로서의 경험을 이야기하는 세션이 있습니다. 해당 영상도 커뮤니케이션에 대한 이야기라서 같이 보셔도 좋겠네요.
2022.07.05 - [테크니컬 라이팅/WTD 컨퍼런스] - WTD 포틀랜드 2022 - 라이트닝 토크 모음
