문서 자동화 과정

요약

이 문서는 Gemini CLI를 써서 SurfAI 프로젝트의 기술 문서를 자동으로 만드는 방법을 알려줘요. 이렇게 하면 문서를 더 쉽고 빠르게 만들고, 항상 최신 상태로 유지하며, 여러 사람이 쉽게 보고 이해할 수 있게 돼요.

전에 기술 문서를 만들 때 이런 어려움이 있었어요:

손으로 하는 작업이 힘들어요: 사람이 직접 문서를 쓰는 건 시간과 노력이 많이 들어요.
그림이나 표 만들기가 어려워요: 문서에 필요한 그림이나 표를 만드는 것도 시간이 많이 걸려요.
여러 나라 말로 번역해야 해요: 문서를 보는 사람이 여러 나라에 있으면, 번역하는 데도 힘이 들어요.
개발 용어가 어려워요: 개발자가 쓰는 전문 용어 때문에 개발자가 아닌 팀원들이 문서를 이해하기 어려웠어요.
개발자가 쉽게 쓰는 게 어려워요: 개발자가 개발자가 아닌 팀원을 위해 쉬운 말로 문서를 쓰는 건 아는 게 달라서 힘들고 번거로웠어요.
개발자가 아닌 사람이 쓰는 게 어려워요: 개발자가 아닌 사람이 문서를 쓰는 건 새로 추가되거나 바뀐 부분에 대해 알아야 해서 역시 어려웠어요.

위에 말한 어려움을 해결하려고 Gemini CLI를 써서 이렇게 자동으로 만들기로 했어요:

문서가 자동으로 바뀌어요: 개발자가 새 기능을 만들거나 고치고 나서 최종 버전에 합치면, Gemini CLI가 관련 내용을 surfai-docs 기술 문서에 알아서 넣어줘요.
그림이나 표가 자동으로 들어가요: Gemini CLI가 프로그램 전체 구조나 기술, 데이터베이스 같은 정보를 알고 있다가 필요할 때 문서에 맞는 그림이나 표(Mermaid로 만든)를 자동으로 넣어줘요.
여러 나라 말로 문서를 볼 수 있어요: Gemini CLI가 문서를 만들고 나면, 영어처럼 필요한 다른 나라 말로도 번역해서 여러 언어로 문서를 볼 수 있게 해줘요.
개발자가 아닌 사람도 쉽게 볼 수 있는 문서를 만들어요: 번역이 끝나면, Gemini CLI가 원래 기술 문서를 개발자가 아닌 팀원도 쉽게 읽을 수 있도록 더 쉬운 말로 바꿔서 문서를 만들어줘요.

이렇게 해결하면서 생길 수 있는 문제점과 그 해결책도 미리 생각해 봤어요:

문서 보기가 불편해요: Gemini CLI가 코드와 문서를 같이 다루지만, 개발자가 아닌 팀원이 직접 코드나 깃(Git)을 보는 건 어려워요.
- 해결책: Docusaurus라는 웹사이트 만드는 도구로 문서를 만들어서 보여줘요. Docusaurus는 개발자가 쓰기 편하고, 마크다운이라는 쉬운 글쓰기 방식도 되고, 여러 나라 말도 지원해서 좋아요.
그림 만들기가 어려워요: 프로그램 구조 같은 그림을 그리는 건 Gemini CLI 혼자서는 어려울 수 있어요.
- 해결책: Mermaid라는 글자로 그림을 그리는 도구를 써요. Gemini CLI에게 우리 프로젝트에 맞는 Mermaid 글자를 만들어 달라고 하면 돼요.
번역이나 쉽게 쓰는 게 들쑥날쑥할 수 있어요: Gemini CLI가 번역하거나 쉽게 쓰는 작업이 항상 똑같지 않을 수 있어요.
- 해결책: .gemini/GEMINI.md나 PRINCIPLES.md 같은 파일에 Gemini CLI가 문서를 만들 때 참고할 규칙을 정확히 적어두면 돼요.

이 모든 과정에서 Gemini CLI가 가장 중요해요. Gemini CLI는 이런 일을 해요:

문서 업데이트 시작: 사용자가 "문서 추가: [내용]"이나 "문서 수정: [내용]"처럼 문서를 고치라고 말하면, Gemini CLI가 문서를 고치기 시작해요.
바뀐 내용 찾기: 사용자가 말한 내용을 바탕으로 바뀐 내용을 알아내고, 필요하면 코드도 살펴봐서 더 많은 정보를 모아요.
알맞은 문서 찾아서 고치기: surfai-docs 안에서 바뀐 내용에 가장 잘 맞는 문서를 스스로 찾아서 고쳐요. (사용자가 어떤 문서를 고치라고 말하지 않아도 돼요.)
바뀐 내용 바로 적용: 문서를 다 고치면, 바뀐 내용을 surfai-docs 저장소의 main 버전에 바로 저장해요. (따로 올리지는 않아요.)

이렇게 자동으로 문서를 만들면 SurfAI 프로젝트의 기술 문서를 더 잘 관리할 수 있을 거예요.