📚 노션 내부 문서 정리, 혼자서 8시간 만에 1,500개 페이지 정리한 방법

 

문서 지옥에서 탈출한 이유, 더 이상 미룰 수 없었다

최근 우리 회사에서 개발자 생산성 조사를 했는데요, 문서화 시스템이 두 번째로 많은 불만을 받았어요. 솔직히 말하면 예상했던 결과였어요. "문서 정리 좀 하자"는 말은 수도 없이 나왔지만, 실제로 행동으로 옮기는 사람은 아무도 없었거든요.

저도 그냥 넘어갈 수 있었지만, 이번엔 좀 달랐어요. 실제로 효과가 있는 변화를 만들어야겠다고 생각했죠. 그래서 혼자서 8시간 동안 집중해서 작업한 결과, 1,500개가 넘는 오래된 페이지를 정리하고 문서 시스템을 완전히 개선할 수 있었습니다.

노션을 사용하는 기업이 빠르게 늘고 있어요. 2024년 기준 노션의 기업 사용자는 전년 대비 40% 이상 증가했다고 하는데요, 그만큼 문서 관리의 중요성도 커지고 있죠. 오늘은 제가 실제로 적용한 구체적인 방법과 노하우를 낱낱이 공유해드릴게요.

우리 회사 노션이 엉망이 된 6가지 진짜 이유

2025년 1월, 우리는 컨플루언스에서 노션으로 마이그레이션했어요. 그런데 이 과정에서 명백히 잘못된 오래된 페이지들이 대량으로 남아있더라구요. 이런 페이지들이 존재한다는 것 자체가 전체 문서에 대한 신뢰도를 떨어뜨렸죠.

더 큰 문제는 일관성 부족이었어요. 어떤 내용을 Git으로 관리하고 어떤 걸 노션에 둬야 하는지 기준이 없다 보니 중복이 엄청나게 발생했어요. 중복된 문서가 많으니까 사람들은 기존 문서를 수정하기보다 새로운 버전을 만들어버렸습니다. N개의 버전이 있는데 왜 그런지 찾기보다 N+1번째를 만드는 게 더 쉬웠거든요.

게다가 지난 1년간 신입 직원들이 많이 합류했는데, 이들은 자신이 문서를 수정할 권한이 있는지 확실하지 않았어요. 누군가 관리하는 문서인지 아닌지 알 수 없었던 거죠. 실제로 2024년 조사에 따르면 기업 내 직원의 68%가 필요한 문서를 찾는 데 하루 평균 30분 이상을 소비한다고 해요.

여기에 노션 AI를 주요 검색 수단으로 사용하기 시작하면서 상황이 더 복잡해졌어요. 계층 구조가 덜 중요해진 대신, 구석에 숨어 있는 부정확한 정보 조각들이 검색 결과에 나타나 혼란을 주게 됐죠.

노션의 API 제약도 문제였어요. 일반 페이지의 검증 상태를 API로 확인할 수 없고, 팀스페이스의 모든 페이지를 한 번에 가져올 수도 없었어요. 보관 기능도 없어서 문서를 검색 결과에서 제외할 방법이 없었습니다.

우리가 세운 새로운 원칙, 문서 관리의 5가지 철학

이 문제들을 해결하기 위해 명확한 정책을 세웠어요. 막연하게 "깔끔하게 정리하자"가 아니라, 구체적인 행동 기준을 만든 거죠.

첫째, 노션 AI 검색 결과를 최적화하는 데 집중했어요. 이제 대부분의 사용자는 직접 링크나 노션 AI로 문서를 찾지, 수동으로 탐색하지 않더라구요. 그래서 FAQ 페이지처럼 중복 콘텐츠를 만들어 방치하는 건 오히려 해롭다고 판단했어요.

둘째, 중복되거나 오래된 콘텐츠는 없는 것보다 나쁩니다. 이건 정말 중요한 원칙이에요. 프로세스에 대한 자체 가이드를 작성하지 말고, 원본 문서로 링크를 걸거나 원본을 업데이트하는 방식으로 바꿨습니다.

셋째, 버전 관리 시스템의 자연스러운 문서화를 선호해요. Github의 README를 노션에 복사하기보다 링크로 연결하는 게 훨씬 낫죠. README는 코드와 함께 관리되니 최신 상태를 유지할 가능성이 훨씬 높거든요.

넷째, 모든 사람이 문서를 정리합니다. 작은 실수를 하더라도 문서를 개선하려고 시도하는 사람이 되는 게, 나쁜 상태로 방치하는 것보다 백배 낫습니다.

다섯째, 자동화가 수동보다 항상 우선이에요. 바쁜 팀이 일관되게 수동으로 콘텐츠를 관리하는 건 현실적으로 불가능해요. 선별적 관리는 좋지만, 전체를 수동으로 관리하는 건 무리죠.

자동화 스크립트로 1,500개 페이지 정리한 구체적인 방법

정책을 세웠으니 이제 실행이었어요. 핵심은 노션의 제약을 우회하는 창의적인 솔루션을 만드는 것이었죠.

먼저 "보관 예정"과 "보관" 팀스페이스를 만들었어요. 보관 팀스페이스는 비공개로 설정해서 검색 인덱스를 오염시키지 않도록 했죠. 반대로 보관 예정은 공개로 두어 누구나 루트 문서에 보관할 문서를 추가할 수 있게 했어요.

매주 자동으로 실행되는 스크립트가 보관 예정의 모든 문서를 보관으로 이동시켜요. 노션의 제약 안에서 찾은 가장 효과적인 보관 메커니즘이었죠.

다음으로 만료된 페이지를 정리하는 스크립트를 만들었어요. 루트 페이지에서 재귀적으로 계층 구조를 구축하고, 각 페이지와 모든 자식 페이지의 마지막 수정일을 확인해서 N일 이상 수정되지 않은 페이지를 모두 정리했어요. 가장 관련성 높은 최상위 페이지 3~4개에 이 스크립트를 실행했더니 약 1,500개의 만료된 문서가 보관됐습니다.

세 번째 스크립트는 오래된 계층 구조 안에 숨어 있는 현재 페이지를 찾아냈어요. 예를 들어 15개의 부정확한 문서 사이에 하나만 업데이트된 경우를 말하죠. 이런 "묻힌 현재 페이지"를 찾아서 상위로 승격시키고, 부모 페이지와 오래된 자식들을 보관 예정으로 옮겼어요.

이 스크립트는 후보를 찾아주고 제가 하나씩 승인하거나 거부하는 방식으로 작동했어요. 가장 큰 문제는 API에서 검증 상태를 확인할 수 없어서 특정 페이지와 하위 항목들을 보호할 방법이 없다는 거였어요.

네 번째로 404 링크를 찾는 스크립트를 만들었어요. 계층 구조를 재귀적으로 탐색하며 끊어진 링크를 찾아냈죠. 중요한 건 이 스크립트가 보관 팀스페이스에 접근하지 못하게 해서 보관된 문서들이 404로 표시되도록 한 거예요. 대량 이동 후 이 스크립트를 실행해서 사람들이 볼 수 없는 보관 문서로 연결된 링크들이 남아있지 않도록 했습니다.

핵심 페이지는 직접 손으로, 품질을 보장하는 수동 검토

자동화 스크립트를 모두 실행한 후, 핵심 페이지들은 직접 검토했어요. 자동화가 80%를 해결했다면, 나머지 20%는 사람의 판단이 필요했거든요.

모든 신입 직원 문서를 확인해서 최상위 온보딩 가이드에 연결되어 있는지, 명확한 전제 조건이 명시되어 있는지, 문제가 생겼을 때 도움받을 슬랙 채널이 안내되어 있는지 점검했어요. 그리고 Git으로 관리되는 README를 복제하지 않고 적절히 링크하도록 수정했죠.

최상위 엔지니어링 및 기술 페이지들도 가볍게 검토했는데, 다행히 이쪽은 상태가 괜찮았어요. 기술 팀이 평소에 문서 관리를 비교적 잘하고 있었던 거죠.

8시간 투자가 만든 변화, 그리고 그 이후

전체 작업에 제 시간은 약 8시간 정도 들었지만, 다른 팀원의 시간은 전혀 필요하지 않았어요. 그리고 이 작업이 우리 문서의 품질을 크게 개선했을 거라 확신해요.

여전히 특정 영역에서 해야 할 일이 많지만, 중복이 훨씬 줄었고 우리가 문서를 적극적으로 관리하고 있다는 증거가 생겼다는 점이 중요해요. 이제 팀원들도 문서를 더 신뢰하고, 수정하는 데 주저하지 않을 거예요.

실제로 한 연구에 따르면 잘 정리된 문서 시스템은 개발자 생산성을 평균 25% 향상시킨다고 해요. 문서를 찾는 시간이 줄어들고, 중복 작업이 사라지고, 온보딩 기간도 단축되니까요.

많은 기업이 문서 정리를 미루거나 대규모 프로젝트로 접근하다가 실패해요. 하지만 명확한 정책과 간단한 자동화만 있으면 혼자서도 단기간에 큰 변화를 만들 수 있다는 걸 이번 경험으로 증명했습니다.

핵심 정리, 노션 문서 정리의 성공 포인트

노션 문서 정리에서 가장 중요한 건 "보기 좋게 만들기"가 아니라 "실제로 작동하게 만들기"예요.

중복과 오래된 콘텐츠는 과감하게 제거하고, 모든 팀원이 문서 정리에 참여하도록 문화를 만들며, 수동 작업보다 자동화를 우선시하는 것. 이 세 가지만 지켜도 문서 시스템은 살아있는 자산이 될 수 있어요.

여러분 회사의 노션도 정리가 필요하다면, 오늘 소개한 방법을 참고해서 작은 스크립트 하나부터 시작해보세요. 8시간의 투자가 팀 전체의 생산성을 바꿀 수 있습니다. 완벽하게 하려고 미루지 말고, 지금 당장 시작하는 게 가장 중요해요. 문서 정리는 한 번에 끝나는 프로젝트가 아니라, 계속 진화하는 시스템이니까요.