구름에서 진행하는 커밋 세션에 오랜만에 참석했습니다.
이번 커밋에서는 Line의 전정은 연사님이 “기술 문서에도 엔지니어링이 필요하다”라는 주제로 강연을 진행해 주셨습니다.
문서와 개발은 떼려야 뗄 수 없는 관계죠?
저 역시 효율적인 업무방법을 찾아서, 다양한 문서 작성 도구를 활용하며 작업하고 있습니다.
현재 진행 중인 프로젝트에서는 Notion, Figma, Google Spreadsheet, ERD Cloud 등을 이용해 회의 기록과 제품 명세를 작성하고, Storybook과 Swagger를 통해 개발 소프트웨어 문서를 관리하고 있습니다.
효율을 찾아서 선택한 문서화 도구들이지만, 이렇게 많은 도구를 사용하다 보니, 문서 관리 도중 다양한 문제가 발생하고있습니다.
한 문서의 수정이 있을 때마다, 해당 내용을 다른형태로 다루고있는 문서를 찾아 업데이트를 해주어야합니다.
이를 정확히 추적하지 못하면, 종종 문서 간 내용 불일치가 발생하기도 합니다.
또, 도구가 워낙 많으니 새로운 도구를 도입하는 일은 팀에 적지 않은 부담이 됩니다.
이렇게 문서화와, 그 도구에 치이던 와중, 요번 구름커밋 초대장이 이메일로 날아와서 냉큼 참가를 신청했는데,
감사히도 당첨되어 다녀올 수 있었습니다.
- 인증숏 (걍연 내용이나, 진행 중에는 촬영 및 녹화가 불가능합니다)
강연 내용
개발 문서 관리의 중요성
- 문서는 신뢰할 수 있어야 한다
기술 문서는 개발 과정의 중요한 의사소통 수단이며,
코드와 동일한 수준으로 신뢰할 수 있어야 합니다.
하지만 개발 과정에서 문서와 실제 구현 내용이 어긋나는 경우는 흔히 발생합니다.
회의를 통해 작성된 명세서를 기준으로 개발을 시작하지만, 고객 요구사항이 변경되는 일도 잦고,
또 프로젝트의 진척에 따라 안 보이던 문제들이 드러나면서, 구현 방향을 바꾸기도 하지요.
이로 인해 초기 명세 문서와 구현 결과가 다른 경우가 생기며,
문서와 코드 간 불일치로 인해 고객과 개발팀 간의 혼란과 불화를 초래하기도 합니다.
따라서, 기술 문서가 신뢰성을 유지하려면 지속적으로 업데이트되고 코드와 동기화 상태를 유지해야 합니다.
연사님께서도 기술문서 담당자 포지션으로 업무를 수행하면서 현장에서 실제 문서와 구현내용이 무척 달라
당황스러울 때가 종종 있었다고 하십니다. 그래서 “기술 문서도 코드만큼이나 신뢰할 수 있어야 한다”는 철학을 가지고
기술문서 전문가로서 활동을 하고 계신다고 합니다.
- 코드보다 문서가 때로는 더 나은 의사소통 도구이다
“개발자는 코드로 소통한다”라는 말 많이 들어보셨지요?
하지만 연사님은 업무 과정에서 문서를 통한 소통이 코드보다 더 원활할 때가 많다고 말씀하셨습니다.
코드는 개발 지식이 있는 사람만이 읽고 이해할 수 있고, 또 개발자들 간에도
서로의 코드를 읽고 이해하는 데 일반 문서보다 더 많은 시간이 소요되기도 하니까요.
반면에 일반 문서는 PM, 개발자, 고객, 디자이너, 경영진 등 다양한 독자가 읽고 이해할 수 있어,
코드에 비해 더 넓은 범위의 사람들과 더 빠르게 의사소통 하는데에 유리합니다.
“개발자는 코드로 소통한다”라는 통념을 전적으로 반박하는 주장이지만, 저는 완전히 동의할 수밖에 없었습니다. 저만 해도 코드를 보기 전에 PR, 커밋 제목, 그리고 주석(존재한다면)을 먼저 읽으니까요.
기술 문서의 도전 과제와 요구사항
개발 프로젝트가 진행되는 생태계는 빠르게 변화합니다.
고객의 요구사항 만큼이나 사용하는 기술, 언어도 점차 복잡해지고 있지요.
연사님은 이러한 배경하에 기술문서의 요구사항 또한 점점 더 복잡해지고 있다고 합니다.
이 자리에서 소개된 대표적인 요구사항들은 다음과 같습니다
1. 버전 관리기술
문서는 SW와 발맞춰서 지속적으로 업데이트가 되어야 합니다.
그리고,또 이전버전의 SW에 대한 문서도 볼 수 있어야 하므로 변경 이력과 히스토리도 조회할 수 있어야 합니다.
2. 편집과 관리의 용이성
여러 사람이 문서 편집에 쉽게 참여할 수 있어야 합니다.
또 인터넷 연결이 되지 않아도 사용할 수 있는 형식의 파일이나 프로그램으로 작성되면 좋습니다.
3. 다국어 지원
글로벌 환경에서 기술 문서는 다양한 언어로 제공될 필요가 있습니다.
다국어의 지원은 기술 문서의 접근성을 높이고, 더 넓은 사용자층을 포용하는 데 있어 중요한 역할을 합니다.
가장 직관적인 예시로, 실제 개발 환경에서 사용되는 라이브러리 문서의 경우, 원전은 대부분 영어로 작성됩니다.
하지만 많은 사용자들이 한국어와 같은 모국어로 번역된 문서를 필요로 하죠.
그래서 , 다국어 지원을 하지 않는 문서라고 하더라도, 자원봉사자들이 커뮤니티 차원에서 번역 작업을 진행하여,
해당 언어권의 사람들도 문서를 읽고 이해할 수 있게 돕죠.
4. 데이터 변환 요구
기술 문서는 단순히 정보를 전달하는 역할을 넘어 데이터로 활용될 가능성도 고려해야 합니다.
다양한 형식(format)으로 쉽게 변환할 수 있는 유연성이 중요합니다.
문서화 추천 도구
위에서 나열한 요구사항을 달성하기 위해서는 문서화에 어떤 도구를 사용하면 좋을까요?
연사님은 기술문서에 사용할 수 있는 워드 프로세서, 노션, 마크다운등도구들을 차례로 소개하시며 그 장단점에 대해 설명해 주셨는데요.
그 중 저 요구사항을 가장 수월하게 충족할 수 있는 것은 "Markdown + git"조합이라고 합니다.
Markdown은 러닝 커브가 낮고, 편집 시 인터넷 연결이 필요 없으며, 형식 변환이 쉽습니다.
또 Git과 함께 활용하면 SW코드를 다루듯 문서의 버전을 체계적으로 관리할 수 도 있죠.
이렇게 Markdown과 Git을 활용하면 문서를 마치 SW코드처럼 다룰 수 있어 이를 “Docs as Code”라고 부릅니다.
이미 대중적으로 사용되는 방식으로 많은 프로그래밍 기술 라이브러리들이 SSG 프레임워크를 활용하여
문서를 웹페이지 형식으로 배포하고있지요.
개인적인 소감
저는 연사님이 추천한 Markdown + Git 문서관리 체제에 순식간에 매료되었습니다.
Markdown 형식으로 문서를 작성하면 필요할 때 SSG(정적 사이트 생성기) 도구를 교체하는 것만으로
새로운 형태의 문서를 생성할 수 있고, 러닝 커브도 낮습니다.
또, 문서 작성 업무를 개발 프로세스에 자연스럽게 녹여도 어색하지 않으니까요.
우연하게도 저희 팀도 최근 지출을 줄이기 위해, 팀 Notion 구독을 취소하고 GitHub로 명세 문서를 옮기는 작업을 진행했는데요. 앞으로도 협업 문서 도구가 필요할 때는 Markdown + Git을 우선적으로 검토하게 될 것 같습니다.
구름에서는 매달 커밋이라는 이벤트를 통해 연사님들을 초청해서 강연을 진행합니다.
관심이 있으신 분들은 구름의 기술블로그를 종종 방문해보세요.
COMMIT - goorm TechBlog (구름 기술 블로그)
tech.goorm.io