기술 문서의 진화 단계

최근 조직 내부 문서화를 하면서 기술 문서의 진화 단계에 대해서 든 생각을 간단히 남겨본다.

기술 문서에는 진화 단계가 있다. 처음부터 모든 지식을 구조화하고 문서화하는 일은 일어나지 않고, 필요하지 않다. 거의 다음 1단계에서 4단계 정도의 과정을 거친다.

1. 구두로 흘러다니는 지식

• 동료들끼리 이야기하면서 알게되는 지식이다.
• 사람마다 알고 있는 수준이나 내용에 편차가 있다.
• 물론 여전히 각 개인의 맥락에 맞는 정보가 있어 유용할 때가 있다.

2. 흩어져있는 메모(Notion, Slack, ...)

• 구두로 흘러다니는 지식이 과포화되면 메모가 시작된다. 각자 혹은 팀 단위에서 슬랙이나 노션에 알고 있는 것을 정리해 둔다.
• 메모이기 때문에 인스턴트해서 쉽게 정보의 신선도가 떨어진다.
• 다만 정보 전달력이나 검색이 된다는 점에서 구두 지식보다는 훨씬 유용하다.

3. 정리된 문서 1단계

• 흩어져있는 메모가 과포화되면 문서를 정리하기 시작한다. 누군가 이 과포화 상태를 해결하려고 한다. 보통 이 작업을 하는 사람은 자기 본업에 더해서 해야하기 때문에 힘들다.
• 문서를 정리하려면 정보를 구조화하고 글쓰기까지 해야하기 때문에 시간과 노력이 많이 든다.
• 문서에 검색 기능을 달기도 한다.
• 어쨌든 한 곳에 문서가 정리되어 있어서 도움이 된다.

4. 정리된 문서 2단계

• 문제를 이해하고 있는 테크니컬 라이터가 개발자의 초안을 가지고 정보를 구조화하고 글쓰기를 한다.
• 문서화 파이프라인을 구축한다.
• 문서에만 신경쓰는 사람이 있어서 훨씬 편해진다.
• 문서를 본 사람들에게는 구조화된 지식이 생긴다.
• 구조화된 지식이 없는, 시작하는 사람은 질문을 하기도 어렵다.

그런데 여기서 더 나아갈 수 있지 않을까?

5. 린터나 봇

• 자동화의 시작 단계. AI의 발전 덕분에 훨씬 더 가능한 일이 많아졌다.
• 문서화가 필요한 코드가 있을 때 문서가 항상 페어가 된다.
• 구조화된 지식이 없는 사람도 질문으로 답을 얻을 수 있다.
• e.g. Inkeep / Copilot for Docs

6. IDE 확장 프로그램

• IDE에 코드를 작성하면 관련된 정보가 함께 나온다.
• 내가 막힌 것을 IDE에서 질문하고, 답을 바로 얻을 수 있다.

---

문서의 가장 중요한 목표 두 가지는 '어떤 정보가 필요할 때 찾을 수 있는 것', '하나의 기술을 깊이 이해할 수 있는 것'이라고 생각한다. 후자는 좋은 문서를 만들어두는 것으로 달성할 수 있지만 전자는 어렵다. 정적인 문서가 '필요할 때'에 맞춰 말을 걸지는 않기 때문이다. 그래서 AI 답변 툴 같은 것이나마 문서에 적용하기도 한다.

보통 우리는 '기술 문서'라고 하면 검색이 되는 정적 사이트를 떠올린다. 개발자가 코드를 짜다가 필요한 정보를 필요할 때 보고, 찾는 행동을 떠올린다. 하지만 일을 하다가 '다른 사이트'에 접근해서 '검색'을 하는 행위는 자연스럽지 않다. 사실상 업무 플로우를 깨는 것에 더 가깝다.

또 문서를 제공하는 입장에서 만든, 생산자 입장에서 재해석한 정보 구조를 이해해야 한다는 것도 허들이다. 어떤 도구를 완전히 처음부터 이해해야하는 상황에서는 그런 구조화가 도움이 될 때도 있지만, 모든 상황에서 도움이 되진 않는다. 그래서 사실상 유저에게 필요한 정보를 '필요할 때 제공한다'는 목표는 정적인 사이트 형태의 문서에서 온전히 달성하기는 어렵다.

그래서 기술 문서는 궁극적으로 업무 흐름에 통합된 개발자도구가 되어야 한다고 생각한다. 정적인 문서 사이트를 만드는 것만으로는 충분하지 않다. 개발자가 사용하는 다른 도구(Linter나 Copilot 등)처럼 개발자의 업무 플로우에 완전히 녹아들 수 있어야 한다. 각 개발자가 처한 매 컨텍스트에서 적절한 정보를 제공해야 하는 것이다. IDE 안에서 문서에 정돈된 내용을 제공할 수 있어야 할지도 모른다. AI가 발전되어 훨씬 쉬운 일이 될 것 같다.

모든 것을 마지막 단계의 도구 하나로 해결할 수는 없다. 전체적인 그림을 보고 싶을 때, 모르는 걸 모르는 상태일 때는 잘 구조화 되어 정리된 글이 항상 도움이 된다. 아는 것을 더 확실하게 이해할 때도 마찬가지다. 그리고 거기에 더 쉽게 접근할 수 있도록 만드는 방법이 필요하다.