개발자는 대체로 문서 작업을 "오버헤드"로 받아들이는 경향이 있습니다. 품질 관리자 가운데는 이런 경향에 섭섭함을 토로할 분도 계시겠습니다만, 이건 엄연한 사실입니다. 개발자 가운데, 문서를 요구하는 관리자와 언쟁을 벌여본 경험이 없는 사람은 없을 겁니다.
http://www.challengefuture.org/news/707
개발자에게 한가지 불행한 일은, 누군가는 그렇게 생산된 문서를 본다는 사실입니다. (편의상 문서 소비자라고 해 봅시다.) 그러니 문서화를 완전히 피할 방법은 없지요.
문서 소비자에게 불행한 일은, 개발자가 생산한 문서 가운데 상당수에 적힌 내용이 실제 소프트웨어와 다르다는 사실입니다. 그런 상황이라면 소프트웨어를 만든 사람의 역량을 의심하게 되는 것도 무리는 아니지요.
이 불행은 무엇에서 비롯된 것일까요? 저는 '가치'에 대한 오해에서 비롯되었다고 봅니다. 개발은 고객에게 반드시 전달되어야 하는 가치를 만드는 행위입니다. 그렇다면 문서는 어떻습니까? 고객에게 보여주어야 하는 문서라면, '문서화'의 목적 또한 '고객에게 가치를 전달하는 것'이 되어야 마땅합니다. 내부 개발자들만이 공유할 문서라면요? 그럴 때는 이야기가 좀 달라집니다. 개발자들만이 볼 문서라면, 개발자들에게 최선의 가치를 전달할 수 있는 형태의 문서가 되어야 맞습니다. 관리자에게 보고할 문서라면요? 관리자들이 개발 진행상황을 쉽게 이해할 수 있도록, 최대한 간략화되고 개조식으로 정리된 문서가 되어야 맞을 겁니다. 그것이 관리자가 요구하는 '문서의 가치'이니까요. (관리자에게 가장 중요한 것은 '의사결정'임을 상기합시다.)
자. 그렇다면 우리는 비교적 쉽게, 문서화를 하는 데 있어 지켜야 할 원칙들을 뽑아낼 수 있을 것 같습니다. 문서화 작업에 있어서 우리가 지켜야 할 원칙들은, 의외로 우리가 개발할 때 지키는 원칙들과 비슷합니다.
1. 단순성 (Simplicity) - 쓸데 없는 이야기를 하지 않는다.
문서를 만들 때 중언부언 하지 않습니다. 가치에 반하는 것은 없앱니다. 개발자 내부적으로만 공유할 문서에 참여자들의 사인을 전부 받을 필요는 없습니다. 그런건 이슈 관리 시스템의 동료 검토 기능을 활용하면 됩니다. 개발자들만 볼 문서에 API의 상세 스펙을 넣을 필요는 없습니다. 그런건 JavaDoc에나 넣으면 됩니다. 단순하게 만들면 정보 중복이 줄어들고 관리 비용이 하락합니다. 필요한 내용만 넣고, 쓸데 없는 건 다 빼버리세요. 그런건 누가 요구할 때나 추가해 넣으면 됩니다 (규칙 5 참고).
2. 무결성 (consistency) - 소프트웨어의 실제 상태에 부합한다.
문서는 언제나 소프트웨어의 실제 상태에 부합해야 합니다. 고객이 어떤 사람이건 간에, 실제 상태에 부합하지 않는 문서는 언제나 실패한 문서입니다. 실패한 문서를 만들지 않는 몇 가지 방법이 있습니다. 첫 번째는 필요한 순간에 문서를 만들어 전달하고 해당 문서에 유효기간을 두는 것입니다 (규칙 4 참고). 두 번째는 개발자로 하여금 언제나 문서 창을 열어놓고 시스템을 변경할 때 마다 문서까지 변경하도록 요구하는 것입니다. 세 번째는 개발자가 언제나 주석에 가장 정확한 내용을 반영하도록 권하고, 필요할 때마다 주석에 적힌 내용을 갈무리해 문서를 만드는 것입니다. (세 번째 가이드라인을 따르는 문서가 JavaDoc같은 것입니다.)
3. 독자 지향 (reader-oriented) - 문서를 읽을 사람을 고려한다.
문서를 읽을 사람이 용역을 준 갑이라면 클래스 다이어그램이 필요할 것입니다. 그러나 고객이 시스템 사용자라면 클래스 다이어그램까지 그려진 문서를 주는 것은 과도합니다. 그런 경우에는 웹에 '사용자 가이드'와 'API 명세서'만 올려놓으면 충분합니다. 누가 문서의 고객인지를 생각하고, 거기 맞는 문서를 만드세요. 10명도 안되는 팀에서 다섯명 정도의 개발자들만이 돌려볼 문서라면, 아예 문서화를 포기하는 것도 생각해 보세요. 그런 팀에서라면 문서화 보다 잡담을 장려하는 쪽이 훨씬 나을지도 모릅니다. (그 팀의 진정한 목적이, 고객에게 '훌륭한 소프트웨어'라는 가치를 전달하는 것이라면 말이에요.)
4. 적시성 (timeliness) - 문서가 필요한 시점을 고려한다.
프로토타이핑이 진행된 결과로 이미 돌아가는 시스템이 있는 상태인데 굳이 설계 문서를 만들어서 클래스 다이어그램을 넣을 필요는 없습니다. 그런 것은 고객의 요구가 없는 한, 쓸데 없는 짓입니다. 문서가 여섯달 뒤에 필요한데, 지금부터 문서를 작성하는 것도 쓸데 없는 짓입니다. 그렇게 되면 문서의 무결성을 확보하기 위해 너무 많은 수고를 들여야 합니다 (규칙 2 참고). 언제 문서가 필요한지를 보고, 그에 맞는 문서화 계획을 세우세요.
5. 요구 지향 (demand-oriented) - 문서에 대한 고객의 요청을 고려한다.
요청이 있다는 것은 고객이 문서를 통해 얻고자 하는 가치가 있다는 뜻입니다. 고객의 요구를 추정하다보면 문서에 너무 많은 내용을 담게 됩니다. 한 번에 완벽한 문서를 만들기 보다는, 고객의 요구를 받아들여 필요한 문서를 작성하는 것이 바람직합니다. 위키는 이런 용도에 적합한 시스템입니다. 위키에 기록된 사항만 언제나 무결하게 정리해 놓으면, 고객의 요구에 즉시 응답할 수 있습니다. 새로운 요청은 위키에 먼저 반영하여 고객의 반응을 살피고, 고객이 만족할 때 공식 문서로 변환할 수 있습니다. 그러니, 필요하지도 않은 문서를 만드는 데 너무 많은 시간을 쓰지 마세요.
그리고 이 모든 원칙들이 너무 복잡하다면, 이것만 항상 생각하세요. '이 문서는 고객(문서를 읽을 사람)에게 어떤 가치를 주게 될까?' 이것만 기억한다면, 과도한 문서화의 함성에서 조금은 벗어나게 될 수도 있습니다.