기술 문서, 이제 그래프로 관리해야 하는 이유: Neo4j와 GraphRAG 활용법

• Graph Data Science

요약: 이 블로그 게시물에서는 기술 문서를 어떤 식으로 구성하는 게 좋을지, 즉 그래프 형태로 구성하는 방법에 대해 이야기해볼 거예요 (차트랑 헷갈리시면 안 돼요!).

소프트웨어 개발자이자 글 쓰는 사람으로서, 저는 매뉴얼, 마케팅 자료, 웹사이트 글, 지원 문의, 버그 리포트, 블로그 포스팅, 컨퍼런스 발표 등 다양한 관점과 형식으로 소프트웨어에 대해 글을 쓸 기회(이자 의무)가 많았어요.

사람들은 다 제각각이라, 그룹으로 묶고 분류하려고 해도 초보 사용자, 입문자, 배우려는 사람, 고급 사용자, 개발자, 관리자, 전문 비평가 등 여전히 다양한 그룹이 존재하죠.

대상 그룹마다 기술 문서에 대한 요구사항은 다르지만, 한 가지 공통점이 있어요. 대부분의 소프트웨어는 사용자가 쓰려고 만든 거니까, 문서는 소프트웨어를 어떻게 써야 개별 목표를 달성하고 만족할 수 있는지 알려줘야 한다는 거죠. 사용자가 없으면 소프트웨어는 무쓸모니까, 문서는 항상 사용자는 물론 사용자의 만족도까지 고려해서 작성해야 해요.

통찰력을 얻는 과정은 선형적이지 않아요.

미지의 영역(여기서는 기술 소프트웨어처럼 복잡한 것)에 접근할 때, 우리는 보통 신중하게 단계를 밟고, 여기저기 테스트도 해보고, 보고 경험한 것을 바탕으로 이해하려고 노력하잖아요?

우리는 각자 다른 성격에 따라 시행착오를 거듭할 수도 있고, 결국 매뉴얼을 찾아보게 될 수도 있어요. 대부분의 경우, 사람들은 곧 문서를 읽으면서 방법, 실용적인 팁, 참조 문서, 그리고 FAQ를 왔다 갔다 하게 될 거라고 생각해도 무방할 것 같아요.

시행착오를 통해서든, 문서를 읽든, 새로운 것을 탐구하면서 통찰이 발전하는 과정은 예측하기 어렵죠. 새로운 분야에 접근하는 인간의 학습 곡선이 꽤 가파르긴 하지만, 더 중요한 건 적어도 우리 대부분에게는 그게 완전히 비선형적이라는 점이에요.

문서는 사람들이 막혔을 때 도움을 주거나, 다음 단계로 나아갈 수 있도록 지혜를 제공하기 위해 존재해야 해요. 반면에, 전통적인 기술 문서는 선형적이고, 종종 인쇄된 문서처럼 구성되어 있죠 (색인이 있는 장과 섹션의 나열처럼요).

그 이상의 구조가 있다면, 그건 그냥 트리 구조일 뿐이에요. 장과 하위 장으로 나뉘는 거죠. 그게 전부예요. 이런 방식은 스토리텔링에는 좋을 수 있지만, 비선형적인 학습 경로를 지원하는 데는 최적이라고 할 수 없어요.

작가의 편견

기술 문서를 작성하는 건 정말 어려운 일이에요.

다음과 같이 간결하고, 단순하며, 정확하고, 감정적이지 않은 언어를 사용해야 할 뿐만 아니라 (물론 문서 유형에 따라 다르겠지만요). 이 트윗을 보면 정말 인상적이죠:

How my career in technical writing ruined me as a letter writer pic.twitter.com/atLXrxRCXb

— 칼 코바치(@karlkovacs) 2016년 4월 3일

좋은 문서는 포괄적이고, 정확하며, 편견이 없어야 해요.

만약 여러분이 특정 문제에 대한 전문가가 아니라면, 아마 그 문제에 대해 글을 쓰고 있지도 않겠죠. 여러분이 글을 쓸 수 있게 해주는 건 여러분의 특별한 지식이지만, 그 지식은 여러분을 여러분 자신의 맥락과 편견에 가두기도 해요. 개발자로서, 여러분은 자신에게는 너무나 당연해서 사소하게 느껴지는 지식이 다른 사람에게는 없을 거라고 생각하고, 매우 기술적인 속어로 설명하려는 경향이 있죠.

계속해서 글을 쓸 때, 텍스트의 어조를 바꾸지 않으려고 일정한 스타일로 쓰는 경향이 있어요. 소설에는 좋을 수 있지만, 폭넓은 독자층의 요구를 충족시키기에는 부족할 수 있죠.

최대 직관의 길

모든 사람이 깨달음에 이르는 서로 다른 비선형적인 방법을 택하기 때문에, 우리 각자에게는 한 이정표에서 다음 이정표로 문제를 해결해 나가는 최적의 경로가 항상 존재해요.

이것이 제가 "최대 직관의 길"이라고 부르는 것이에요. 이는 인간이 기존 맥락에 가깝고, 이용 가능한 지식과 함께 이미 신뢰하는 사실과 경험에 기반할 때 새로운 것을 배우는 데 에너지를 덜 쓴다는 원칙에 기반하고 있어요.

특정 상황에서 다음 단계는 뭘까요? 사용자가 생각하지 않고도 이해할 수 있는 단어로 복잡한 주제를 어떻게 설명할 수 있을까요? 아이들이 개인적인 맥락에 연결되기 때문에 복잡한 상호 관계를 더 쉽게 이해하도록 하려면 어떻게 해야 할까요?

물론, 그건 모두 독자가 가지고 있는 지식과 맥락, 그리고 독자의 입장에서 생각하는 작가의 능력에 달려 있어요. 결과적으로 모든 것에 맞는 단 하나의 경로는 없고, 가장 좋은 단 하나의 경로도 없으며, 심지어 "황금 중간 경로"조차 없어요. 이 모든 것은 어느 정도 수용 가능한 타협점이 될 뿐이죠.

해결 방법: 그래프 사용

해결책은 간단해 보일 수 있어요. 문서를 그래프로 구성하는 거죠.

독자가 하나의 선형적이고 평면적인 섹션 순서를 따르도록 강요하는 대신, 기사나 항목 간에 다양한 경로를 제공하는 거예요. 초보자와 전문가를 위한 다양한 스키 슬로프가 있는 것처럼, 파란색부터 빨간색, 검은색까지 다양한 색상으로 연결부를 표시할 수도 있겠죠.

하나의 문서 항목에서 다음 항목으로 나가는 연결을 두 개 이상 제공함으로써, 사용자가 자연스러운 직관에 따라 문서를 통해 개별 경로를 찾을 수 있도록 도와주는 거예요. 이렇게 하면 창의적인 작업에 필요한 에너지를 절약할 수 있죠.

저희는 Structr에서 위에서 언급한 모든 아이디어와 기능을 아직 구현하지는 못했지만, 새로운 문서 사이트는 모든 잠재력을 담은 그래프에요. 저희는 그걸 Structr Knowledge Graph라고 부르고 있어요.

공식 기술 문서 외에도, 도움말 기사, FAQ, 튜토리얼, 설명 비디오는 물론 Stack Overflow 질문, GitHub 문제, 또는 토론 스레드에 대한 링크가 있고, 이 모든 것들이 그래프의 node들이에요.

저희의 목표는 수동 분류, Natural Language Processing (NLP), 그리고 원본 콘텐츠 소스에서 추출된 최대한 많은 정보를 혼합해서 Structr에 관한 모든 것에 대한 최고의 지식 소스를 만드는 것이에요.

저희는 Structr Knowledge Graph를 개선하기 위해 끊임없이 노력하고 있고, 사용자를 지원하고 행복하게 만들기 위해 점점 더 많은 콘텐츠와 기능을 추가할 거예요. 🙂

Structr는 다음의 골드 스폰서입니다.GraphConnect Europe. GraphConnect에 등록하고 2016년 4월 26일 런던에서 Axel과 나머지 Structr 팀을 만나려면 아래를 클릭하세요.

• Graph
• GraphConnect
• Natural Language Processing
• nlp
• Structr

---

에이치시스템즈의 LogTree는 Neo4j 기반 GraphRAG 플랫폼으로, 데이터를 자동으로 지식그래프화하고 자연어 질의로 즉시 답을 제공합니다.

👉 에이치시스템즈 홈페이지