엔지니어링 지식 지도 만드는 법
팀 문서가 부족할 때는 모두가 문서를 더 쓰자고 말합니다. 하지만 시간이 지나면 반대 문제가 생깁니다. 문서는 많은데 어디에 무엇이 있는지 모르고, 오래된 문서와 최신 문서가 검색 결과에서 섞입니다. 이때 필요한 것은 문서 양이 아니라 지식 지도입니다.
지식 지도는 목차보다 넓다
단순한 폴더 구조나 위키 목차는 문서의 위치를 보여줍니다. 지식 지도는 문서가 어떤 문제를 해결하는지, 누가 소유하는지, 언제 검토해야 하는지, 어떤 시스템과 연결되는지를 함께 보여줍니다. 사용자는 파일명을 찾고 싶은 것이 아니라 지금 내 질문에 답하는 문서를 찾고 싶어 합니다.
좋은 지식 지도에는 다음 메타데이터가 필요합니다.
- 주제와 하위 영역
- 문서 소유자
- 마지막 검토일
- 관련 서비스나 저장소
- 결정 기록, 런북, 튜토리얼 같은 문서 유형
이 정보가 있으면 검색과 탐색이 모두 좋아집니다.
문서 유형을 섞지 않는다
문서가 혼란스러워지는 큰 이유는 목적이 다른 글이 같은 모양으로 쌓이기 때문입니다. 결정 기록은 왜 그렇게 했는지를 남기고, 런북은 장애 상황에서 무엇을 할지 알려주며, 튜토리얼은 처음 배우는 사람을 안내합니다. 세 문서를 한 글에 섞으면 어느 순간 아무 용도에도 맞지 않습니다.
지식 지도는 문서 유형을 드러내야 합니다. 사용자는 빠른 복구가 필요한지, 배경 이해가 필요한지에 따라 다른 문서를 열어야 합니다.
오래된 문서를 처리하는 법
오래된 문서를 무조건 삭제하면 과거 맥락이 사라집니다. 하지만 오래된 문서가 최신처럼 보이면 더 위험합니다. 문서에는 상태가 필요합니다. active, needs-review, deprecated, archived처럼 상태를 표시하면 검색 결과에서도 신뢰도를 판단할 수 있습니다.
검토일이 지난 문서는 자동으로 소유자에게 알리고, 소유자가 없는 문서는 팀 단위 검토 큐로 보내는 방식이 현실적입니다.
체크리스트
- 문서마다 소유자와 검토 주기를 둔다.
- 결정 기록, 런북, 가이드, 레퍼런스를 구분한다.
- 검색 가능한 태그와 관련 시스템 정보를 넣는다.
- 오래된 문서는 상태를 표시하고 최신 문서로 연결한다.
- 온보딩 경로와 장애 대응 경로를 별도로 만든다.
엔지니어링 지식은 저장한다고 살아남지 않습니다. 찾을 수 있고, 믿을 수 있고, 갱신될 때 팀의 실제 도구가 됩니다.
Continue Reading
다음으로 읽기 좋은 글
엔지니어링 문서 검색 구조 설계
문서가 많아질수록 문제는 작성보다 탐색이 됩니다. 검색 가능한 문서 구조를 어떻게 설계할지 실무 관점에서 정리합니다.
🔧 Tools엔지니어링 노트 운영법
기억에 의존하는 개발은 쉽게 반복 비용을 만듭니다. 개인과 팀이 함께 쓰는 엔지니어링 노트 운영법을 정리합니다.
📚 IT 이야기개발자들은 왜 CLI를 사랑하게 되었을까
화려한 GUI가 많은 시대에도 개발자들은 여전히 터미널로 돌아갑니다. CLI가 기술 문화의 중심이 된 이유를 이야기처럼 풀어봅니다.
🤖 AI / LLMOpsAI 에이전트 가드레일: 도구를 쓰는 에이전트를 안전하고 유용하게 만드는 법
도구 권한, 계획 검토, 승인 체크포인트, 실패 경계, 감사 가능성을 포함해 AI 에이전트 가드레일 설계를 실무 관점으로 정리합니다.
다음 탐색