왜 당신의 Engineering Wiki가 묘지가 되었는가 (그리고 이를 고치는 방법)

Source: Dev.to

당신도 그 느낌을 알 겁니다. 파일을 열고, 스파게티 같은 코드 블록을 바라보며 “왜 이렇게 만들었을까?” 라고 생각하죠.
위키를 확인합니다. 마지막 업데이트는 2024년에 회사를 떠난 누군가가 3년 전에 한 것이었습니다. 슬랙을 확인합니다. 결정은 6개월 전의 스레드에 묻혀 있는데, 정확한 키워드를 기억하지 못해 찾을 수 없습니다.

이것이 지식 묘지이며, 팀의 속도를 죽이고 있습니다. 개발자로서 우리는 코드를 작성하고 싶지, 역사책을 쓰고 싶지는 않죠. 지식이 문을 나가버리거나 소음 속에 묻히면, 우리는 오래된 결정을 다시 설명하거나 새로운 직원을 급히 온보딩하는 데 ~30 %의 시간을 소비하게 됩니다.

아래는 이 문제를 해결하기 위해 고안된 도구들의 개요이며, 우리가 혼란에 지쳐 직접 만든 도구부터 시작합니다.

Syncally.app

Best for: 컨텍스트 자동화를 원하는 팀, 단순히 문서만 작성하는 것이 아니라.

Full disclosure: 저는 매주 같은 아키텍처 결정을 설명하느라 지친 “과부하된 CTO”였기 때문에 이 제품을 만들고 있습니다.

The Philosophy

대부분의 도구는 문서를 별도의 작업으로 취급합니다. 코드는 한 곳에서 작성하고, 코드를 설명하는 문서는 다른 곳에 씁니다. Syncally는 Unified Workspace를 만들어 작업, 회의, 코드, 캘린더가 한 곳에 함께 존재하도록 뒤집어 놓습니다.

Key Features

• Automatic Context Linking – 코드 커밋을 결정이 이루어진 토론 및 회의와 직접 연결합니다.
• Onboarding Mode – 새로운 엔지니어가 “왜 이렇게 인증을 구현했나요?”라고 물으면 정확한 PR과 해당 결정을 내린 Zoom 회의 녹화본을 가리키는 답변을 받을 수 있습니다.
• Knowledge Graph – 프로젝트, 사람, 결정이 어떻게 연결되는지를 시각적으로 보여주는 지도이며, 변경을 적용하기 전에 그 영향 범위를 확인할 수 있습니다.

Why It Works

Jira, Notion, Slack, Zoom을 오가며 겪는 “툴 피로”를 해결합니다. 왜가 아니라 무엇을 포착합니다.

Glean

Best for: 강력한 내부 검색이 필요한 대기업.

장점

• Universal Search – 모든 것을 인덱싱합니다 (Drive, Slack, Jira, GitHub) 그리고 하나의 검색창으로 모두 검색할 수 있습니다.
• Permissions – 기존 권한 구조를 존중하여 사용자가 볼 수 없는 정보를 보여주지 않습니다.

트레이드오프

Glean은 문서를 찾는 데는 뛰어나지만, 반드시 맥락을 연결해 주지는 않습니다. 구글 드라이브에 안 좋은 문서가 있다면, Glean은 그 안 좋은 문서를 매우 빠르게 찾아냅니다. 바늘을 찾는 데는 도움이 되지만, 건초 더미를 정리해 주지는 않습니다.

Stack Overflow for Teams

Best for: Q&A와 특정 기술 솔루션을 캡처하는 경우.

The “Teams” version brings the familiar Stack Overflow Q&A format inside your firewall.

The Good

• Familiarity – 모든 개발자가 사용 방법을 알고 있습니다.
• Gamification – 찬성표와 채택된 답변이 참여를 유도합니다.
• Specifics – “빌드 스크립트를 어떻게 실행하나요?”와 같은 질문에 적합합니다.

The Trade‑off

완전히 수동 입력에 의존합니다. 누군가가 질문을 해야 하고, 누군가가 답변을 해야 합니다. 회의나 코드 리뷰에서 생성된 암묵적인 지식은 포착되지 않습니다. 아무도 기록하지 않으면 존재하지 않는 것입니다.

Notion

Best for: 유연하고 디자인 중심의 문서화.

Notion은 아름답고 유연합니다; 이를 통해 놀라운 로드맵과 위키를 만들 수 있습니다.

The Good

• Flexibility – 원하는 대로 구조화하세요.
• Collaboration – 실시간 편집이 원활합니다.

The Trade‑off

It is the definition of the “Graveyard” risk. Because it’s so flexible, it requires constant gardening. Without a dedicated technical writer or a very disciplined culture, Notion pages will rot. It’s a blank canvas—which is both its greatest strength and its greatest weakness.

결론