문서, 문서화, 문서관리에 대하여

API 문서를 따라서 호출을 해봤는데, 404 에러가 뜬다. 호출이 되지 않는다. 가이드 문서를 읽으며 SSO 구현을 하고 있는데, 막히는 부분이 있다. 문서를 작성한 담당자에게 질문하고 싶은데, 문서 어디에도 담당자가 누구인지 나와있지 않다.

정책 관련 문서를 봤는데 2017년에 작성했다고 한다. 지금은 2023년, 이 문서를 과연 믿어도 될지 모르겠다.

큰 회사를 다닐수록 흔히 경험하게 되는 문제다. 그리고 이 문제는 Notion을 써도, 컨플을 써도 똑같다.

왜 문서는 항상 문제가 되는가

최신화가 안된 문서

조직이 성장하고 시간이 흐르면 오래된 문서가 늘어난다. 많은 문서가 관리되지 않은 채 방치되며 어느 순간부터는 문서를 어디까지 믿어야할지 알 수 없게 된다. 문서를 따라 API를 적용해 봤는데 호출이 안 되기도 하고, 문서를 신뢰해도 되는지 작성자에게 물어봐야 해서 불필요한 커뮤니케이션 비용이 증가한다.

작성자나 책임자가 모호한 문서

글을 작성한 사람이 명시되지 않은 글이라면, 문서가 최신이 아니라는 것을 알았을 때 누구에게 물어봐야 하는지 알 수 없게 된다. 혹은 문서의 내용이 불충분해도 어디에 물어봐야하는지를 찾기 위해 시간을 낭비하게 된다.

경우에 따라서는 작성자가 팀 이동을 했거나 퇴사한 경우도 있을 수 있다. 이 경우, 문서는 주인을 잃고 방황하게 되며 어느 누구도 문서에 대해 책임을 지지 않게 된다. 결국 그 문서는 있으나 마나 한 문서가 되고, 어느 누구도 그 문서를 신뢰할 수 없다.

불충분한 문서

애초에 문서의 양 자체가 불충분한 경우도 많다. 특히 스타트업일수록, 신생기업일수록 이 문제는 두드러진다. 팀에 새로운 입사자가 들어왔는데, 문서가 없어서 누군가가 설명을 해줘야 한다. 막힐 때마다 슬랙이나 협업툴로 질문을 계속 던져야 해서 실무자는 일에 집중을 할 수가 없다.

코드에 주석이 부족하다. 프로젝트가 오래 되어 코드를 작성한 개발자는 팀 안에 없다. 물어볼 사람도 없고, 주석이 부족해 코드를 사용하는 것도 부담된다. 결국 똑같은 서비스를 다시 개발하게 되기도 한다.

권위가 불분명한 문서

조직이 커지면 다양한 이유로 문서가 작성된다. '나중에 스스로 보려고' 부터 '팀원간 교류를 위해', 심지어는 '사내 라이브러리 공식 문서'까지. 각 문서별로 권위나 공식성은 천차만별이다.

조직이 충분히 크다면 유사한 주제, 유사한 제목의 문서가 조직 곳곳에 산재한다.

예를들어, "클라우드 인스턴스 신청 방법"에 대해 DevOps 팀에서 작성한 공식 문서부터 프론트엔드 팀의 신규 입사자 온보딩 문서, 개발자 개인의 목적으로 작성된 문서까지 동일 주제로 다양한 문서가 있을 수 있다.

이 경우, 상대적으로 DevOps팀의 공식 문서가 가장 신뢰할만한 문서이며, 개발자 개인 문서함의 문서가 가장 신뢰하기 어려운 문서이다.

문제는, 문서를 검색하는 측에서는 이 공식성을 판단하는 데 한계가 있다는 것이다. 어떤 팀이 어떤 주제에 대해 가장 권위를 가지는지 알지 못한다면, 결국 모든 문서를 읽어봐야 하는 비용 낭비가 발생하는 것이다.

왜 문서화는 천덕꾸러기 취급을 받는가

개발자들은 문서작업을 싫어한다. 그들은 코드작업과 문서작업이 서로 다른 작업으로 인식하며 흔히 '기획자의 일'이라고 생각하기도 한다.

적어도 코드를 짜는 일보다는 지루하고 따분하며, 자신의 경력에도 도움이 안 된다고 생각한다.

문서는 자신보다 타인을 위한 경우가 많다

하다못해 테스트코드는 스스로에게도 도움이 된다.

  1. 코드의 품질이 향상되어 엔지니어로서 좋은 평가를 받을 수 있다.
  2. 결함이나 버그가 줄어들어 스스로 유지보수할 때 도움이 되며 잠재적인 장애로 인한 평판 하락을 방지해준다.

하지만 문서는 앞도적으로 자기 이외의 사람들을 위한 것이다. 문서작성자는 보통 그 문서의 내용을 명확히 숙지하고 있고, 문서는 자신보다 타인에 의해 훨씬 더 많이 읽힌다.

즉, 작성자와 혜택 수혜자가 다른 문제가 있다. 혜택 수혜자는 스스로의 노력과 무관하게 무료로 혜택을 얻는다. 잘 정리된 라이브러리 사용법은 라이브러리 개발자보다는 사용자에게 혜택을 준다.

문서 작성이 개발자 평가에 영향을 주지 않는다.

아쉽게도 많은 회사들이 개발자의 실력을 평가할 때 문서작성능력을 함께 평가하지 않는다. 개발자의 퍼포먼스는 대개 그들이 얼마나 빨리 얼마나 많은 기능을 구현하느냐로 평가되는데, 이 조건을 만족하다 보면 문서작성이나 테스트코드 작성, 리팩토링은 후순위가 되기 싶다.

그나마 개발문화가 좋은 기업들은 테스트코드나 리팩토링도 평가에 반영시켜 강제성을 부여하지만, 그마저도 문서작성은 상대적으로 등한시 하는 경우가 많다.

코드 작성 프로세스와 문서 작성 프로세스가 분리되어 있다.

많은 문서가 코드와는 별개로 작성된다. 물론 예외도 있다.

  • 주석
  • README, CHANGELOG
  • SWAGGER나 OPEN API와 같은 API 문서화 도구

하지만 대부분의 README가 기획적인 측면을 심도있게 다루지는 못한다. 즉, TechSpec으로서 기능하지는 않는 것이 현실이다.

대부분의 개발자는 코드 작성이 자신의 일이라 생각하고 문서 작성은 코드 작성과는 동떨어진 별개의 일로 인식하는 경향이 있다. 코드 작성과 문서 작성이 완전히 분리되어 있다면, 문서 작성은 기획자의 일처럼 여겨지기 쉽다.

그러다보니 코드를 작성한 후 수고스럽게 문서를 작성하는 것은, 모두가 꺼려한다.

해결책: 어떻게 문서를 챙겨야 하는가

인사 평가 요소에 문서 작성 역량을 포함

개발자를 평가하는 평가요소에 문서 작성 역량을 포함시킨다. 평가만큼 구성원을 동기부여하는 강력한 도구는 없고, 문서작성이 조직에 이롭다면, 당연히 이는 평가요소로 반영되어 강제성을 띄게 해야 한다.

BARS(Behaviorally Anchored Rating Scale)처럼 행동 기반으로 조직원을 평가한다면, 문서작성 행동을 하는지 리더가 직접 평가하게 할 수 있다.

만약 공식적인 평가 프로세스가 부재한 상황이라면 평가권자에게 평가요소에 대해 가이드라인을 제공해 참고하게 할 수도 있을 것이다.

문서에 적절한 소유자와 유효기간을 명시

구글 등 기업에서는 문서의 OWNER와 신선도 보증기간(유효기간)을 명시한다고 한다.

---
OWNER: @superman
EXPIRE_AT: 2025-05-01
---

OWNER는 지금 이 문서의 책임자를 의미한다. 작성자일 수도 있고 아닐 수도 있다. 문서의 독자는 누가 작성했는지 알 필요 없이 문서에 대해 궁금증이 생기면 OWNER에게 물어보면 된다. 모든 책임은 OWNER가 진다.

유효기간은 조직별로 적절한 가이드라인을 둘 수 있을 것 같다. OWNER와 유효기간을 파싱하는 프로그램을 둬서 유효기간 만료 전 OWNER에게 알람이 가게 할 수도 있을 것이다.

유효기간의 장점은 유효기간이 지난 문서는 자연스레 '이 문서는 정확하지 않을 수 있다'는 암시를 독자에게 전달한다는 것이다. 따라서 문서가 정확할 것이라 믿고 불필요한 시간을 낭비하는 일을 줄일 수 있게 된다.

문서 리뷰 제도 도입 및 문서 버전 관리

문서도 코드처럼 리뷰가 필요하다. 문서의 작성이 1인에게만 달릴 경우, 잘못된 내용이나 이해하기 어려운 내용 위주가 될 수 있다. 다음 관점들에 의해 필히 리뷰를 거치도록 해야 한다.

  • 정확성: 설계가 코드를 정확히 반영하는지, 기술적 결함은 없는지, 잘못된 개념은 없는지 등 주로 기술적 요소와 관련된 기준이다. 팀 내 동료나 도메인 전문가가 리뷰한다.
  • 명확성: 문서를 읽고 활용하려는 이 입장에서(독자 입장에서) 이해하기 쉬운지, 누락된 개념이나 정보는 없는지와 관련된 기준이다. 사용측 혹은 독자가 리뷰한다.
  • 일관성/가독성: 다른 문서와의 일관성, 문장이나 문단의 가독성을 리뷰한다. 테크니컬 라이터(Technical Writer)나 기획자, 작문 실력이 좋은 사람이 리뷰한다.

문서 리뷰는 반드시 팀 외부의 공정한 제 3자의 리뷰를 거치게 한다. 팀 외부인이 최소 1인 이상 LGTM 태그를 달아야 리뷰 프로세스가 완료될 수 있게 해 공정성을 확보한다.

자동화된 툴로 문서 트래킹 및 갱신 알람

데몬이나 스케줄러로 동작하는 문서 관리 애플리케이션을 개발하고 운영한다. 문서관리 애플리케이션은 각 문서의 OWNER와 유효기간을 읽어와 유효기간이 다가오는 문서들의 경우 OWNER에게 메일, 슬랙 등으로 알림을 준다.

유효기간이 경과한 문서는 자동으로 별도의 아카이빙 디렉토리로 이동시켜, 누구나 이 문서가 더 이상 유효하지 않음을 이해하기 쉽게 한다. 더불어 유효기간이 경과한 문서를 자동으로 아카이빙 하면, 문서를 작성한 팀이 동일 문서를 다시 작성하는 일이 없기 위해서라도 문서를 최신화하게 동기부여하는 효과도 있다.

참고자료

  • <구글 엔지니어는 이렇게 일한다>, 한빛미디어