SI 프로젝트의 문서는 왜 만들까?

SI 산업 가이드북 ⑭

AI의 시대, 하지만 SI는 갈 길이 멉니다. 옛날에 비해 많이 변하긴 했지만 그래도 여전히 그대로죠.

특히 산출물만큼은 옛스러움을 답습하고 있습니다. 다른 사람에게 일을 맡긴다는 특성상 어쩔 수 없기도 하지만, 산출물 받는 사람들이 개발할 사람이 아니기 때문에 개선할 필요성을 못 느끼거든요. 공공사업 쪽은 규제처럼 정해져 있어 안 만들 수도 없습니다.

그러다 보니 프로젝트에 투입된 초보 개발자는 정말 영문도 모른 채 산출물을 만듭니다. 왜 필요한지, 언제 필요한지도 모르죠.  그래서 진짜 필요한 내용이 안 담깁니다. 최근 어떤 프로젝트에 들어갔더니, 문서는 많은데 볼만한 게 하나도 없더라고요.

그래서 ‘SI 프로젝트 산출물’에 관한 내용을 정리해 보았습니다.

문서화

문서는 왜 만들까요?

좀 오래되긴 했지만, 지난 1998년 스위스의 한 기관이 연구를 했습니다.

“프로젝트팀의 업무 시간은 어떻게 쓰일까?” 이런 주제였죠.

결과가 이렇게 나옵니다.

“프로젝트팀은 전체 시간의 27%를 업무 파악에 쓰고, 고객 요구사항 분석에 24%, 설계에 18%, 구현 18%, 테스트에 13%를 쓴다. 전체 업무의 33%는 재작업에 쓴다.”

재작업이란 소위 삽질을 말합니다.

이 중에서 구현, 테스트는 AI의 도움을 받기에 딱 좋습니다. 하지만, 업무 파악과 요구사항 분석, 설계는 그렇지 못하죠. 기업 업무는 케바케가 엄청 많거든요. AI가 돕긴 하지만, 일일이 확인을 해야 합니다.

즉, 1998년부터 이어져 온 주요 업무의 약 69%는 여전히 사람이 해야 하는 일입니다. 이걸 잘못하면 재작업 33%는 사라지지 않죠.

시스템 구축이란, 세상에 없던 걸 새로 만드는 작업입니다. 그러다 보니 사실 고객도 모릅니다. 뭘 만들어달라고 해야 할지 말이죠. 요구사항을 정리할 수 없으니, 개발할 수도 없죠.

더군다나 개발 과정은 눈에 보이지 않습니다. 문제가 있다면, 뭔가를 볼 수 있을 때쯤 이게 아니라는 걸 깨닫게 되죠. 시간이 한참 흐른 후입니다. IT 프로젝트의 오랜 숙명이죠.

한편 문서는 눈에 보이지 않는 모든 것들을 보이게 만들기 위한 수단입니다. 보면서 오류를 바로잡자는 거죠. 살필 시간이 없다면 문서의 가치는 사라집니다. 

그런데 대부분의 SI에는 문서 살필 시간이 없죠. 문서를 보는 것보다 그냥 담당자에게 물어보는 게 제일 정확하고 빠르니까요.

그렇다면 문서는 왜 필요할까요?

첫째, 개발하면서 계속 봐야 하는 문서들이 있습니다. 코드로는 표현 못 하는 전체 그림이죠. 이런 문서는 설계도라고 합니다. 코드를 읽어서 클래스(Class) 간 관계를 확인하는 것보다, 그냥 화살표로 그려진 그림을 보는 게 빠릅니다. 좀 더 한눈에 들어오기 때문이죠.

화살표가 복잡할수록 더욱 그렇습니다. 퐁당퐁당 건너뛰는 트랜잭션이라면 꼭 그림이 있어야 하죠.

둘째, 물어볼 사람이 없는 경우입니다. 개발이 끝나고 운영이 시작되었을 때 이야기죠. 개발한 사람은 없고 복잡한 구조를 설명해 줄 사람도 없습니다. 문서가 유일하게 기댈만한 곳이죠.

그래서 개발 단계에선 “과정 문서”가 많이 필요합니다. 소통에 필요한 내용을 그림으로 표현해 놓은 거죠.

반면 운영 단계에선 “과정 문서”가 필요 없습니다. 나 혼자 일을 하고, 고칠 부분도 많지 않고, 소통할 사람도 적으니까요. 대신 전체 그림이 필요합니다. 그것도 최신판으로요. 내가 딱 고칠 부분만 알아내면 되거든요.

스타트업은 운영 중에 신규 기능을 개발합니다. 그래서 SI 운영보다는 문서가 복잡합니다. 데이터와 기능이 자꾸 변하다 보니 최종 버전 관리가 잘 안되죠. 그냥 적절히 관리합니다.

아무튼 이렇게 문서도 필요에 따라 달라집니다. 필수 문서가 있을까요? 

SI 할 때 반드시 작성되는 문서들이 있습니다. 초보자들은 잘 모릅니다. 정리해 봅니다.

업무 구성도

업무 구성도는 업무를 정리한 그림입니다. 전체 업무와 하위 업무를 상세하게 그려줍니다.

그림 속의 업무는 은행 수신 업무의 구성도입니다. 은행 창구 직원들이 쓰는 프로그램의 메뉴이기도 합니다.

이런 걸 표현할 때는 전문용어를 해석하지 않습니다. 그냥 그대로 정리합니다. 직원들이 쓰는 용어이기 때문입니다.

은행에선 “돈”을 “신용”이라고 부릅니다. 그래서 예금업무를 “수신”(신용을 받는다)이라고 합니다. “유동성신규”는 입출금이 자유로운 자유 예금, “정규성신규”는 일정 기간 비치해 놓는 정기 예금, “적립성신규”는 적금 예금을 말합니다.

시스템에서는 일반적으로 메뉴 하나에 메인 화면 하나를 매칭합니다.

‘신규계좌조회, 해지계좌조회? 이건 하나로 만들면 더 좋지 않을까, 왜 두 개를 만들었을까?’ 은행 구성도를 볼 때는 이런 생각을 하면 안 됩니다. 은행업무 시스템의 사용자는 일반인들이 아니거든요. 창구 직원들이 사용자입니다.

해지계좌는 손님들이 문제를 제기할 때 들여다봅니다. 상담이 발생할 때죠. 해지 사유, 지급 이자, 해지 처리 담당자, 정확한 해지 일시 등의 정보들이 상세하게 기술되어 있어야 합니다.

화면이 필요한 상황은 일반인이 겪는 상황이 아닙니다. 그래서 창의적으로 생각하면 안 되고, 개선이 필요하면 직접 당사자에게 물어봐야 합니다.

즉, 업무 구성도는 고객의 언어로 만들어진 개발 목표이자 프로젝트의 범위입니다.

개발 요구사항을 정리해 놓은 뼈대이기도 하고요. 그렇기에 프로젝트를 시작하면 가장 먼저 만들어야 할 문서입니다.

다만 빠지는 것들이 있습니다. 고객도 모르는 것들이죠. 보안관리, ID 인증, 통계 업무 같은 것들입니다. 이런 업무는 창구 직원이 아니라 전산실 직원이 하는 일이니까요. 그래서 업무 구성도를 정리할 땐, 관계된 사람들을 모두 고객이라고 생각하고 만나야 합니다.

시스템 구성도

시스템 구성도를 보겠습니다.

여기서 시스템이란 한 대의 서버를 말합니다. 옛날에는 시스템 = 서버 한 대 = 업무 하나였거든요. 그래서 시스템 구성도가 업무 구성을 담고 있습니다.

요즘에는 그렇지 않습니다. 단순히 업무에 따라 서버를 나누지 않고 기능별로 분리하기도 합니다. 지금의 시스템 구성도는 소프트웨어 구성도와 비슷해져 버렸죠. 그래서 요즘에는 “시스템 개요도”, “업무 시스템 개념도” 등으로 부릅니다.

자세히 보면 업무들이 계층적으로 정리되어 있습니다. 그래서 각 업무의 종속관계, 연관관계 등을 이해할 수 있습니다. 시스템의 업무 범위도 알 수 있죠.

이를테면, 이미지 가운데 영역의 “계정계”란 “계정”을 중심으로 이루어지는 업무들입니다. 우체국에서는 예금 업무도 하지만, 보험 업무도 합니다. 이 그림을 보면 알 수 있죠.

“정보분석/활용”이 이러한 “계정계”와 같은 레벨에서 다루어집니다. 중요도가 높겠군요. 독립 시스템으로 운영되는 걸 보니 담당 부서도 다르겠네요.

이미지 왼쪽 “채널 서비스”란 소통 채널을 말합니다. 방송 채널을 생각하면 쉽죠.

데이터는 “계정계”에서 가져오고, 인터넷, 스마트폰, 폰뱅킹 등을 통해 고객과 소통합니다.

둘을 함께 그려놓은 건 DB가 같거나 역할이 유사하기 때문입니다. 보안 정책 관리 등이 유리하죠.

시스템 구성도를 통해 이런 것을 읽습니다. 코드를 만들고 유지 보수하기 위한 중요 자료들이죠.

물리적 시스템 구성도

옛날 그림을 가져왔습니다. 요즘도 클라우드가 아닌 전통적인 서버를 구성할 땐 이렇게 구성합니다. 클라우드 시스템도 구성 원리가 비슷하니 참고할 수 있습니다.

물리적 시스템이란, 손으로 만질 수 있는 “하드웨어 서버”를 말합니다. 요즘에는 서버 한 대에 700만 원 정도 합니다. 옛날에는 한 대에 4~5억 원씩 했습니다. 성능과 스펙에 따라 돈이 많이 들어갑니다. 그래서 어떤 걸 사고 어떻게 준비해야 할지 미리 정해야 합니다. CPU, 메모리, 스토리지 등등을 말이죠.

그런데 그걸 정리하려면 어떤 소프트웨어를 쓸지, 속도는 얼마나 빨라야 할지도 알아야 합니다. 그러려면 아직 만들어지지 않은 소프트웨어의 성능을 대충 예측할 수 있어야 하죠.

예를 들어 거래 로그가 하루에 천만 개씩 쌓이고 3개월을 보관해야 한다면, 약 9억 개의 로그 저장공간이 필요합니다. 로그 파일 하나에 1Kb를 차지한다면, 약 900GB의 스토리지가 필요하겠네요. 프로그램 공간까지 고려한다면 약 1.5 TB짜리 스토리지를 사야 합니다.

다만 로그 데이터라면 굳이 좋은 곳에 담아둘 필요가 없습니다. 읽지 않고 보관만 하다가 사고 발생 시에 열어보면 되니까요. 읽기 쓰기가 느려도 저렴하면 좋습니다.

이렇게 파일별로 보관 정책도 분리할 수 있죠.

물리적 시스템 구성도는 이런 일을 구분하기 위해 그립니다. 그리고 이 결정은 하드웨어 구매 예산에 그대로 반영되죠.

AWS 구성도도 사실 같은 목적으로 그립니다. 전산실 운영자 입장에선 거의 1대1로 매칭되죠. 서버를 실 구매할 필요가 없을 뿐, 해야 하는 일은 거의 똑같습니다.

클라우드를 도입할 때 비용 예측을 안 하는 경우도 꽤 많습니다. 요즘에는 전산실 업무를 잘 아는 개발자가 많지 않거든요. 그래도 중대형 SI는 대부분 전산실이 있다 보니, 이런 걸 해달라고 합니다. 운영할 때 서버 비용은 중요하니까요.

간혹 서비스가 이제 시작해서 가입자가 1천 명이 안 되는데, AWS 서버 비용만 매월 천만 원씩 나오는 경우도 생깁니다. 기업형 SI에선 있을 수 없는 일이죠. 할 이야기가 많은데, 다음 기회에 다뤄보겠습니다.

시스템 소프트웨어 구성도

레거시가 많은 시스템을 연동해야 할 땐, 이런 그림들을 보게 됩니다. 마찬가지로 옛날 그림이죠.

요즘은 대부분 리눅스(Linux)를 쓰다 보니 이렇게까지 복잡하진 않습니다. 소프트웨어 스택이 일반화되었죠. 그래서 노션(Notion) 같은 문서 프로그램에 “표”로 정리합니다. 그림이 보기 좋긴 하지만, 표가 더 간단하죠.

시스템 소프트웨어란, OS 위에 설치해야 하는 기본 프로그램들을 말합니다. 옛날 서버들은 OS가 달라서 저런 걸 정리해야 했습니다. 실제 운영이 이뤄지는 환경이다 보니 “운영 환경”이라고 부릅니다.

보통 “개발 환경”에서 디버깅을 뺀 구성이라고 생각하면 됩니다.

메모리, 연결선 등도 중요한데, 특히 “버전”을 눈여겨봅니다. 옛날 버전을 쓰는 경우도 많거든요.

JDK를 요즘 버전으로 개발했다가 이 서버에 올리면 안 돌아가는 경우도 많습니다.

그래서 가능하면 서버별로 자세하게 그려줍니다. IP, 프로토콜(protocol), 네트워크 포트(network port) 같은 것도 기록하죠. 시스템 운영에 필요한 거라면 모든 정보를 한데 모아서 기록합니다.

소프트웨어 구성도를 그릴 때 엄격한 기준이 있는 건 아닙니다. 필요한 게 있다면 자유롭게 그립니다. 목표는 소통과 이해를 돕는 것입니다. 장애가 났을 때 이 그림을 딱 펴면 어디서 문제가 났는지 알 수 있어야 합니다.

그래서 이 그림은 운영팀에게 매우 중요합니다. 이게 없다면 “상용 서버” 관리자가 없다는 겁니다. 큰 회사라면 보통 담당자가 있지만, 작은 기업이라면 없는 경우도 많습니다. 그래서 프로젝트가 끝나도 이런 그림이 안 생기는 경우가 많습니다.

문서가 없는 시스템에 신규 기능을 만들러 새로운 개발자가 들어오면 이 그림부터 파악하느라 시간이 한참 걸립니다. 엔지니어링에 서툰 초보 개발자라면 이런 관계를 몰라서 코딩을 시작하지도 못합니다.

그런 사람이 많냐고요? 많습니다. 특히 신입사원들은 이런 걸 배울 기회가 더욱 없으니 말이죠.

애플리케이션 구성도

애플리케이션 구성도. 애플리케이션이란 개발팀이 만드는 프로그램을 말합니다. 실제로 동작해야 하는 프로그램들이죠.

게시판 만드는 거라면 굳이 이런 게 필요가 없습니다. 클래스(Class) 몇 개로도 끝나거든요. 그런데 은행 업무 같은 건 그려야 합니다. 클래스 몇천 개가 복잡하게 얽혀 있거든요.

이거 꼭 필요할까요? 사실 코드란 건 이렇게 짜도 돌고, 저렇게 짜도 돕니다. 그래서 개발자들이 자기 스타일대로 만들죠. 하지만, 은행같이 복잡하게 얽혀 있는 업무라면, 업무 간 연관관계를 고려해야 합니다. 예금 잔액을 조회한 후에야 ATM기 출금을 허락할 수 있잖아요.

특히 SI는 복잡한 기능을 한 번에 ‘짠’ 하고 만들어야 하기 때문에 이렇게 설계도를 그려놓고 개발을 시작합니다. 이런 설계도에 클래스 다이어그램(Class Diagram), API 정의서, 화면 설계서 등등이 들어가죠.

실제로 많이 보냐고요? 봅니다. 그리고 봐야 합니다.

산출물로 만들어야 하는 워드나 엑셀문서는 아닐 수 있지만, 우리는 UML 툴을 이용해서 ERD나 클래스 다이어그램을 그립니다. 그렇게 만드는 것들로 화면설계서, API 정의서 등이 있습니다.

이런 문서들은 개발자와 개발자, 설계자와 개발자, 디자이너와 개발자, 기획자와 디자이너 등이 함께 봅니다. 업무 내용을 식별하거나 작업 지시를 하기 위해서죠.

보통 “개발문서”라고 부르는 이런 산출물은 초보개발자들도 많이 보는 편입니다. 그런데 공공 SI프로젝트에선 엑셀, 파워포인트, 한글 문서로 옮겨 적기도 합니다. 사실 좀 불편하죠. 개발자들은 이미 UML 툴이나 피그마(Figma) 등으로 충분하거든요.

요즘에는 이런 작업을 지원하는 도구가 많아지면서 SI 프로젝트에도 변화가 많이 생겼습니다. 다만 대부분 웹 기반 도구라 계정이 있어야 볼 수 있습니다. SI 프로젝트는 이동 인력이 많은 만큼 관리가 불편하긴 하죠. 그래서 최종본을 파일로 출력해서 하나를 관리하기도 합니다.

개발문서는 소통에 반드시 필요한 문서입니다. SI 프로젝트라면 이런 게 안 만들어질 수가 없죠.

이런 문서가 전혀 관리되지 않는 곳도 있습니다. 일이 제대로 진행되지 않고 있다는 겁니다. 그런 곳에 들어가면 챙길 곳을 몰라 한참 헤매기도 합니다. 일정이 촉박하면 아주 난감하죠.

데이터 구성도

모든 기업 시스템은 고객 데이터가 바로 돈입니다. 데이터 구성도는 그러한 비즈니스 가치사슬, 고객 정보를 모두 담은 그림입니다. 일반적으로 기업 비즈니스에서 애플리케이션은 데이터를 만드는  도구일 뿐 핵심이 아닙니다. 데이터가 바로 사업의 정체성이죠.

그래서 데이터 구성도는 모든 기업에서 중요합니다. ERD는 이 구조를 정의한 틀이죠.

어쨌든 반드시 잘 관리되고 있어야 합니다. 정상적인 기업이라면 잘 관리될 수밖에 없습니다.

API를 만들 때도 필요하고, 회계 결산할 때도 필요하고, 서비스 기능을 만들 때도 필요하니까요.

그런데 이런 게 없는 곳도 있습니다. “진짜 없다고?” 물을 수도 있겠네요. 네, 있습니다. 회사가 작아서 개발팀이 없거나 필요할 때만 외주를 주는 회사도 많거든요. 아예 개발 담당자가 없죠.

이런 프로젝트에 들어갔다면, 데이터 구조를 알기 위해 ERD를 새로 그려봐야 합니다. 역공학(Reverse Engineering) 도구들이 있으니 그걸 이용해 봅니다. NoSQL 계열이라면 다른 방법을 써봅니다.

프로젝트 관리문서들

지금까지 본 문서들은 실제로 만들어질 시스템에 대한 것들입니다. 프로젝트 문서(개발문서)들이죠.

목표를 뚜렷이 하고 과정을 드러냄으로써 최종 결과물을 제대로 만들고자 하는 수단들입니다.

SI 프로젝트가 아니라도 쉽게 볼 수 있죠.

그런데 SI 프로젝트에선 “일하는 과정”을 관리하는 문서도 있습니다. 요구사항 변경, 업무량 증가 등 일정과 예산에 영향을 주는 모든 것들을 기록하고 관리하죠. 이런 걸 “프로젝트 관리문서”라고 합니다.

SI는 결국 남의 일을 하는 것이고, 이해관계자 여러 명이 얽혀 있기 때문에 100점으로 끝나는 경우가  절대 없습니다. 책임소재와 갈등, 합의 내역 등을 잘 관리해서 분쟁, 갈등 상황에 대비해야 하죠.

그러다 보니, “관리문서”는 골칫덩어리로 보이기도 합니다. 1억 원짜리면 1억 원어치, 10억 원짜리면 10억 원어치 문서들이 생깁니다. “프로젝트 관리자”인 PM 조직이 살뜰히 문서를 챙기는 이유죠. 개발자 입장에선 고통스러운 일입니다. 일이 잘 끝난다면 쓸데없는 문서가 되니까요.

개발자가 만들긴 해야 하지만, 문서 수요자가 개발자가 아닌 경우도 있습니다. 복잡한 주간 보고 케이스죠. 투입시간으로 관리하다 보니 증명을 위한 문서도 만들게 됩니다.

이번 글의 목표는 시시비비를 가리고자 함이 아니니 여기선 넘어가겠습니다. 다만, ‘프로젝트 관리문서를 어떻게 할 것인가’에 대해선 많은 연구가 필요합니다.

큰 규모든 작은 규모든 SI가 겪고 있는 가장 큰 문제의 집약체이기 때문입니다.

초보 개발자들은 프로젝트 관리문서를 볼 기회가 거의 없습니다. 그냥 문서 담당자에게 물어보는 게 가장 빠르죠.

마치며

정리합니다. 프로젝트 산출물은 크게 “소통”을 위한 문서, “결과”를 보관하는 문서, “과정”을 관리하는 문서, 이렇게 크게 세 종류로 나뉩니다.

“소통”을 위한 문서, “과정”을 관리하는 문서는 프로젝트가 끝나면 보관 효력이 사라지죠. 반면 “결과”를 보관하는 문서는 운영 중에도 지속적으로 읽히며 업데이트됩니다.

문서를 죄악시하는 개발자들이 있습니다. 그건 너무 많이 나가지 않았나 싶습니다.

모든 문서는 필요에 의해 생겼고 그 필요가 여전히 존재하니까요. 외부 개발자가 API를 써야 하는데, 내부 개발자가 API 스펙 문서 하나 못 만들어 주면 부끄러운 겁니다. 텍스트만 적은 워드나 엑셀 문서라도 없는 것보다는 훨씬 낫죠.

다만, 이런 산출물을 어떻게 관리할 것인가에 대한 연구는 거의 멈추었습니다.

요구사항 정의서를 꼭 엑셀로 정의해야 하는가?

요구사항 식별자를 붙여서 이리저리 문서로 관리를 해야 하는가? 

그게 과연 프로젝트를 잘 끝내는 데 중요한 것인가? 

그래서 그걸 좀 쉽게 할 수 있는 방법이 없는가?

이런 질문들이 사라졌죠. 그냥 관행처럼 움직입니다. 이런 관행들은 규제나 정책 하나로 바뀌지 않습니다. 사람과 습관의 문제니까요.

문제를 가장 잘 아는 사람은 문서 템플릿 관리자가 아니라, SI 프로젝트의 구성원들입니다. PPT 문서가 노션과 피그마로 바뀐 것처럼, 프로젝트 팀 내에서 필요성에 대한 질문을 던져보고 개선하려는 노력들이 이어지면 좋겠습니다.

©️요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.