영상버전 : https://youtu.be/pYqlz5DyfzE
IT프로젝트에는 많은 문서가 필요합니다.
하지만 작은 프로젝트나 자사 시스템은 문서가 부족한 경우가 많지요.
그래서 저는 경험이 적은 사람은 외부 SI같은 경험을 통해 문서 만드는 것을 몸에 익히게 하는 것을 추천하고 있습니다. 한국은 경험을 많이 할 수 있으나 남은 문서가 적어 스스로 무얼 했는지 정리하지 못하는 사람들이 많고, 문서가 필수인 일본에 넘어와서는 실력이 좋음에도 문서를 못만들어 평가 절하 되는 경우가 많거든요.
그러면 결국 실력이 있으면서 상류 공정을 뺏기는 경우가 많지요.
항상 프로젝트 또는 사내 기술문서는 내게 아니라고 지나치지 마시고,
열람 권한이 있는 문서는 모두 보고, 스스로 만들어보는 버릇을 들여야 합니다.
그게 단순히 앉아서 코딩하는 것 보다 훨씬 빨리 성장하는. 길이거든요.
그레서 개발자 및 IT엔지니어들이 꼭 봐야 하는 문서를 정리 해 봅니다.
ISP보고서
ISP보고서는 프로젝트 시작 전에 외부 컨설팅 업체에 이 프로젝트의 정당성, 시장상황 등의 큰 그림을 볼 수 있어 프로젝트에 참여한 사람들이 방향을 일치 시키는데 중요한 역할을 합니다. 하지만 ISP보고서 하나 작성에 수억이나 하기 때문에 보통 10억엔 이상 하는 프로젝트가 아니면 없는 경우가 많습니다.
그래도 일본에서는 많은 이유는 IT프로젝트 하나에 수천억엔 하는 경우도 있기 때문에 충분히 볼 기회가 많습니다.
RFP(Request for proposal)
제안 요청서 라고 하는데, 발주사가 나는 이런거 만들테니 제안서좀 가져와봐 하는 제안서를 만드는 기업에 제출하는 사양서 입니다. 보통 여기에 기술적 요건들이 들어가는데요..
발주사의 담당자가 전체를 퍼악할 수 없는 경우가 많기 때문에 ISP프로젝트를 진행하는 외부 컨설팅 업체가 발주사의 환경을 분석해서 만들곤 하는데요. 규모가 작은 경우는 발주사가 자주 발주하는 업체에 요청해서 만들기도 합니다. 때문에 rfp에 침여한 업체는 공모를 했을때 우위에 점하는 기업을 이미 정해서 쥐약 이란걸 넣을 수 있지요. 요건 막 까발릴 수 없으니 제 콘텐츠에서 알아서 파악하시길…
Rfp는 현재 구조, 그리고 어떤게 필요하고, 개발언어, 서버 등의 어떤 제약조건 내에서 만들어야 한다는 내용이 기술 됩니다. 판단에 애매한 상황이 있을 때 PL은 자주 확인하는 문서 입니다.
Rfp에 없는 내용은 안만들어도 되거든요. 믈론 계약서에 있다면 만들어야 하지만요..보통 RFP를 기준으로 계약서를 만들기 때문에 거의 일치 합니다. 계약시 추가 되는 내용이 있기도 하니까 충분히 주의는 해야 합니다.
그래도 계약서는 프로젝트 멤버 전원이 볼 수 있는 곳에 두지 않기 때문에 멤버라면 rfp에 의지하고 pl이나 se가 계약 내용을 확인 해 주어야 합니다.
제안서
제안서는 고객이 프로젝트를 리드 할 업체를 선전하는 기준이 됩니다. 멋드러지게 만드는 경우가 대부분이지만, 가장 중요한 이 프로젝트를 성공시칼 수 았는 요인이 들어가야 하지요.
제안서 하나만 잘 만들어도 수천만엔짜리 프로젝트는 딸 수 있지요.
그래서 제안서만 전문 적으로 만드는 팀에서 1년에 5건 이상 만들어 봤는데요.. rfp가 뜨면 바로 제안서 작성 팀을 꾸리고 거의 2주를 제안서 작성에 몰두 합니다. 각 분야의 사람들이 자기 파트의 제안을 하구요, 그걸 취합해서 그럴싸하게 만들어주는 속칭 이쁜이 작업 담당이 멋지게 이미지 포함해서 표현을 해줍니다. 결과물을 보면 이걸 내가 만들었나 할 정도가 되지요. 하지만, 대부분 rfp에 참여 한 사람들이 프로젝트를 수주하는 경우가 많기 때문에 제안서 작업에 저를 부를 때는 rfp작업에 참여한 업체인지를 먼저 물어봅니다.
아무리 고객과 친밀한 관계에 있더라도 rfp에 참여하지 않았다면 이미 최 상위 조직에서 결정한 업체를 번복할 수 없지요.
갑질로 유명한 그룹 소속의 H모 정보통신에서 S방송사에 제안을 했을 때는 엄청 하드하게 달렸는데 떨어졌는데요.. 그래도 수고했다며 거창하게 뒷풀이를 쏘는 모습은 나름 멋지게 보였습니다. 보통 제안 한번에 날리는 인건비 등의 비용이 거의 5천만원 이상 나가는데 말이어요..
제안서는 SI원청사가 만들지만 내부 인력만으로는 해결이 안되는 케이스가 많기 때문에 이렇게 저 같은 사람은 여기저기서 제안서를 만들고 그 회사 사람인 척 제안 설명도 하지요..^^
NDA나 계약서는 기술과 그다지 상관이 없어서 통과를 하겠습니다.
요건정의서
요건정의서는 계약이 된 시점에 Kick-off 미팅이 시작되면서부터 요건정의 담당자가 고객과의 미팅시마다 나온 이야기 중에 구현해야 한다 판단되는 내용을 적는 문서입니다. 알아서 거르면 안되고 고객이 말한 모든 내용을 정리하여 요건이다 판단되면 무조건 기재를 합니다.
그 뒤에 계약과는 무관하다 판단되는 것을 고객과 협상하여 배제를 하고 그걸 명기해 두어야 하지요. 배제 했다고 문서에서 빼버리면 나중에 논란의 소지가 있기 때문입니다.
요건 정의는 아주 세세하고 꼼꼼하게 할거 안할거까지 다 적어놓아야 하는 중요한 문서인 것이죠.
양식은 크게 필요 없고 그냥 워드 문서 또는 엑셀 같은 문서에 어떤 항목을 언제 고객과 협의하여 할지 안할지를 결정했다는 식으로 표현하면 됩니다.
회의록
회의록은 당연히 엄청 중요한 문서가 됩니다. 회의 시간에 나왔는데 기재가 안되었다면 회람시 고객이 화를 낼 수도 있구요, 누락 된 하지 않기로 한 내용이 그냥 자나가 버리면 할 수 밖에 없는 내용이 되기 때문이지요. 요건이 바뀐 것을 확인 한 고객은 그 시기의 회의록을 달라고 요청하기도 하기 때문에 충분히 주의 해서 관리를 해야 합니다.
기본설계서
기본 설계서는 PM이 작성하는게 기본이구요, 경험이 없는 PM인 경우 외부 PMO를 영입해서 작성을 시키는 경우도 있습니다. 기본설계서만 보면 개발을 할 수 없습니다. 기본 설계서에는 사용할 환경이나 언어는 적혀있으나, 코드에 대한 이야기나 세세한 개발 항목에 대한 내용은 전혀 없지요.
우리는 오피스에 모여서 flutter를 이용하여 클라우드에 이런 식으로 접속하여 이렇게 만들 것이고 조직 구조는 이렇고 이렇게 보안을 지킬 것이다 같은 개괄적인 내용이 전부라서 뭘 해야 할지 알기 힘듭니다.
그리고 여기에 기본 사양서가 첨부되지요.
그리고 기본 설계서와 함께 나오는 것이 시스템 구성도나 ERD, 네트워크 물리/논리 구성 등의 전체 그림이 나옵니다. 심지어는 데이터센터 같은걸 사용하던 시절에는 데이터센터의 전력이나 관리 방안까지 개괄적인 내용을 적기도 했지요.
기본 사양서
사양서는 다양한 곳에서 작성을 하는데 기본 사양서는 포괄적인 프로젝트에 필요한 항목이 적혀 있습니다.
기본 설계서에서 문장으로 만든 내용을 표 형태로 만들었다 생각하면 되구요. 이 내용이 PL들애개 전달되면서 이 내용을 기반으로 상세설계서가 나오게 됩니다.
상세설계서
상세 설계서 부터가 개발자들이 받아서 직접 개발을 할 수 있는 구조가 나옵니다. 시스템 구성도, 요건 정의, 기본 사양서에 있는 기능 목록을 보고 그걸 구현할 최소 단위의 프로그램을 하나의 문서로 축약하는 것이 상세설계서가 됩니다.
상세 설계서는 PL이 만드는게 보통이지만, 경험있는 PG가 있다면 PG에게 넘기기도 합니다.
상세 설계서와 같이 나오는 문서가 IF사양서, 프로그램(Function) 사양서 등이 있습니다.
IF사양서(접속 사양서)
IF사양서는 외부 시스템과의 접속에 필요한 사양서로, 지금 만들고 있는 프로그램을 다른 프로그램이 접속할 때 보고 개발할 수 있게 만들어야 합니다. 때문에 입력, 출력, 에러코드, DFD 등이 있게 되구요, 요즘은 샘플코드와 같이 만들어서 바로 제공할 수 있게 하는 경향이 있습니다.
프로그램 사양서
프로그램 사양서는 각 함수나 라이브러리를 언제 어떻게 호출해서 쓰고 있는지 등을 DFD와 함께 함수 단위로 기재하는 표 라고 보시면 됩니다. 개발이 완료되고 다른 사람이 이 문서만 보면 이어서 수정이나 추가를 할 수 있어야 하므로 그만큼 상세하게 적어야 합니다.
보통 인수인계 라는 것은 이런 문서 목록을 만들어 넘겨주면서 이런 문서들이 뭐하는 것인지만 설명하는 것인데 말로 이런 문서내용을 설명하고 있진 않은지요?
소프트웨어 아키텍쳐
소프트웨어 아키텍쳐도 쉽게 설명하면서 그릴 수 있어야 합니다.
하지만 이게 뭐지? 하면서 두리뭉실하신 분들이 많은 거 같더라구요..
지금 하고 있는 프로젝트를 구성하는 소프트웨어 블록으로 집을 짓는다고 생각하면 됩니다.
개발쪽이라면 하드웨어는 몰라도 되기 때문에 대부분의 경우 맨 아래 토대를 OS로 지정합니다.
OS로 쭈욱 길게 박스를 만듭시다. 이건 뭔지 모르잖아요.. 그래서 추상화 즉, abstraction layer입니다.
그리고 그 위에 사용되는 프레임워크를 올려야지요. DB등의 독립적인 어플리케이션이나 솔루션도 여기에 올리시면 됩니다.
그 위에 이들을 사용하는 라이브러리나 모듈을 올리구요. 이걸 Persistance Layer라고 합니다.
그 위로 개발에 사용되는 Service Function들을 올립니다. 이건 Service Layer.
그걸 이용해서 구현되는 기능을 올리구요. 이걸 Business Layer라고 하죠.
그 기능들이 표현되는 표시 영역을 올리면 됩니다. 이게 Presentation layer라고 합니다.
마지막으로 외부와 연결되는 API나 기타 외부 기능들을 적으면 끝. 위치는 보기 쉬운 곳에 적으면 됩니다.
참 간단하지요?
이렇게 쉽게 5분도 안되서 만들 수 있는게 소프트웨어 아키텍쳐인데... 여러분은 그 동안의 자신의 프로젝트에서 얼마나 소프트웨어 아키텍쳐를 만들어 보셨나요?
시스템 구성도
시스템 구성도는 서버간 또는 IT시스템에 필요한 요소들을 연결할 때 사용하는 구성도 입니다. 여기에는 네트워크가 어떻든 서버나 각 요소들이 어떻게 연결되어 있는지를 간략하게 적기 때문에 하드웨어 지식이 없어도 작성이 가능합니다. 보통 개발PL이 많이 작성하지요.
네트워크 물리 구성도
네트워크 물리 구성도는 네트워크 엔지니어가 L2, L3나 라우터 방화벽 등의 장비가 실제로 어느 기기랑 물려있는지를 적는 구성도로, 서비스 장애가 생겼을 때 가장 먼저 확인해야 하는 구성도 입니다. 이게 있고 없고는 장애의 해결 속도에 큰 영향을 끼치게 됩니다.
네트워크 논리구성도
네트워크 논리 구성도는 네트워크 엔지니어가 작성후에 개발자들에게 공유할 때 사용하는 구성도로 네트워크 장치는 없애고 간략하게 연결고리만 만들어서 제공하는 것이 보통입니다. 때문에 개발시 서버들의 구성을 알기 쉽게 되어 있고, 개발 function등은 들어있지 않은 그림이 되지요.
요즘같은 클라우드 시대에는 물리 구성을 알기 어렵기 때문에 논리 구성만으로 끝내는 케이스가 많습니다.
ERD(Entity Relationship Diagram)
Data의 구성 및 각 attribute의 구성을 연결하는 구성도 입니다. 이전에 제가 좀더 자세히 소개한 내용이 있는데요. 개발을 하면서 어떻게 데이터를 부르고 넣을지를 알아야 하기 때문에 ERD를 읽고 구조를 파악할 수 있어야 합니다. 보통 ERD는 데이터 아키텍트가 만들어주는데 그게 없는 작은 규모는 개발리더가 주로 만들기도 합니다. 한국에선 없는 경우를 너무 많이 봐왔는데요, 저랑 같이 프로젝트 해보신 분들은 ERD가 얼마나 중요한 역할을 하는지 잘 아실 겁니다. draw.io 같은 툴을 사용하면 모든 개발 문서를 연결하는 허브의 역할도 할 수가 있지요.
제가 이번 프로젝트에서 만든 ERD입니다. 일부러 작게 표시한거니 확대하실 생각은 마시길;;;
DFD(Data Flow Diagram)
상세 설계와 함께 나와야 하는 중요한 도식입니다.
각 함수 또는 기능별로 만들어야 하구요, 데이터가 어떻게 흘러서 어디에 저장된다거나 어떻게 변형되고 어느 곳에 보존되는지가 보이는 곳입니다.
DFD만 있으면 개발이 아주 빠르고 쉬워지기 때문에 시간이 없다고 안만드는 것보다 만들고 나서 개발하는 것이 훨씬 시간을 단축하고 나중에 문서 만들 시간도 절약이 되므로, 만드는게 버릇이 되어야 하는 도면입니다.
대충 생각나는대로 훑어 보았는데요,
빼먹은 것이 있으면 나중에 보충을 해보겠습니다.
자신이 지금까지 빼먹고 있던 문서가 있는지, 용도가 잘못된 문서가 있는지 다시 한 번 체크가 되는 기회가 되길 바랍니다.
댓글
댓글 쓰기