세상을 놀라게 하자!

Specification작성 방법-2 본문

Technical writing

Specification작성 방법-2

유진호 2015. 10. 2. 01:44
앞선 글에서 잔소리는 열심히 적어놨는데 어떻게 써야 할지 막막하긴 하다. 그 이유인즉슨 사실 10년 이상 소프트웨어 개발일을 하면서 어떤식으로 Specification을 적어야 하는지 말하기도 전에 그게 왜 필요하냐며 악쓰는 사람들이 더 많았기 때문이다. 부디 그 분들을 위해서 쓴 ‘구전문학 프로젝트 관리’를 참고 바란다. (아니라고는 말 못할 것이다.) 


 단순한 글쓰기를 어떻게 해야 하는가에 대해서는 '한국의 이공계는 글쓰기가 두렵다’같은 책들을 참조하는게 더 나을 것이다. 가장 중요한 것은 먼저 우리가 ‘글을 쓴다’라고 하는 행동을 어떤 식으로 하고 있느냐이다. 단순히 생각나는대로 글을 적는것 역시 ‘수필’로 가치가 있겠지만 지금 우리는 그런 글을 쓰려고 하는게 아니다. 인류가 만든 것 중에서 제일 복잡하고 손으로 잡혀지지 않지만 가장 큰 가치를 만들어 내는 정신활동을 하기 위한 글을 적으려고 하는 것이다. 

 이 과정은 마치 거대한 유화를 그리기 전에 어떤 것을 그릴지를 구상하는 과정과 같다. 그리고 장편 소설을 쓰기 전에 인물과 사건을 미리 구성하고 작성하는 과정과 같다. 



연습 : 스테이크 코스요리를 만들어보자.  



 자, 눈을 감고 머리로 생각을 해보자. 지금 여러분은 아름다운 당신의 연인에게 멋지게 스테이크 코스 요리를 만들어 주려고 한다. 그 전날 미리 재료를 사려고 하는데 당신은 어떻게 하겠는가? 내가 무슨 말을 할지 보지 말고 한번 생각해보자. 어떤 요리를 내야 할까? 

 비록 아마추어 요리사지만 나라면 이렇게 메뉴를 구성할 것이다. 
  • 시작은 가벼운 이탈리아 빵과 올리브유와 발사믹 식초 석은 것을 낸다. 
  • 연어샐러드: 연어와 샐러드, 올리브 유를 뿌려준다. 
  • 스테이크: 등심 200g정도를 미디엄으로 굽는다. 감자와 당근, 브로콜리를 버터와 함께 삶아서 곁들여서 낸다. 와인도 한잔 준비한다. 
  • 후식: 아이스크림에 살구쨈을 곁들여 낸다.

이런 것을 머리속에 먼저 넣고 시장을 가기전에 필요한 재료들을 정리할 것이다.

 그 다음에는 꼭 생각해야 되는 것은 요리 순서다. 빵과 아이스크림, 살구쨈이야 사온 것을 그대로 쓰면 될 것이다.  연어 샐러드는 2,3시간은 냉장고에 있다가 나올 수 있다. 그러므로 미리 해놓는다. 감자, 당근, 브로콜리도 미리 삶아서 냉장고에 넣어놨다가 조리할 때 꺼내서 한번 데우면 되므로 미리 해놓는다. 등심은 미리 적당한 크기로 잘라놓고 식사를 시작하기 직전에 구워야 한다. 스테이크 소스는 내놓기 직전에 뿌려야 한다. 

 자, 이제 머리속에 이런 것들을 생각해 놓았다면 이대로 하나하나 준비하면 된다. 사실 요리를 못하는 사람들의 특징은 바로 이 순서를 머리속에 ‘미리’그리지 못하는 것이다. 실제 최근에 인기를 끌고 있는 ‘집밥 백선생’이란  요리프로에서 외식 경영 전문가 백종원씨가 요리를 가르칠 때 사람들에게 제일 먼저 시키는 것은 ‘어떤 요리를 만들지 미리 생각해봐라’였다. 이것이 가장 큰 ‘비법’이다. 미리 우리가 만들고자 하는 것을 머리속에 ‘그리는’작업, 바로 ‘시각화’다.  시각화 한 다음에는 무엇을 하는가? 바로 ‘조직화’다. 어떤 순서로 일을 할지를 정리를 하는 것이다. 이를 위해 가장 중요한 요소는 바로 각 재료의 특성들이다. 

  이 과정을 한번 소프트웨어 만드는 데 가져오면 어떨까? 눈치가 빠른 사람들은 이미 무릎을 치고 있을 것이다!


우리가 써야 하는 두개의 문서, 그리고 어떻게 써야 하는지 


앞서 말한 스테이크 요리 순서를 생각해면 우리가 써야 하는 문서는 두가지다. 
  • GUI specification (그래픽 사용자 인터페이스 정의 문서)
  • Software design specification (소프트웨어 설계 정의 문서)

GUI specification (그래픽 사용자 인터페이스 정의 문서)는 아래 요소들을 담는 문서다. 
  • 소프트웨어를 사용하는 사용자에게 어떤 것을 보여줄지를 적는다. 
  • 각 상황별로 어떤 화면을 보여주어야 할지를 적는다. 
  • 이 문서를 읽은 사람이, ‘아, 이런걸 만드는 거구나’라고 시각적으로 그릴 수 있어야 한다. 

Software design specification (소프트웨어 설계 정의 문서)는 아래 요소들을 담는 문서다. 
  • 소프트웨어를 구현하기 위한 기술적인 설명이 들어가야 한다. 예를 들어 어떤 프레임워크로 작업할 것이고 어떤 패턴으로 구현하게 될것인지를 적어야 한다. 
  • 소프트웨어 전체를 구성하는 각 요소들이 어떤 관계를 가지고 구성되어야 할 지 관계를 그린다. 
  • 이 문서를 읽은 사람이, '이 소프트웨어는 이렇게 구현하면 되겠구나'라는 생각을 하며 소프트웨어를 개발할 순서, 모듈들을 머리에 떠올릴 수 있어야 한다. 
그리고 모든 문서 작성시 반드시 따라야 하는 원칙이 있다. (제발 이거 좀 해줘라...)
  • 모든 문장은 능동태로 적어야 한다. 
  • 모든 문장에서 형용사와 부사가 없어야 한다. 

문서를 작성하는 과정이 중요하다

 이런 의문이 들 것이다. "그럼 문서만 잘 만들면 모든 것이 다 되는가?" 이미 정답을 알고 있다. 그렇지 않다.  그럼 왜 이렇게 강조하는 것일까? 이런 문서들을 작성한다고 생각해보자. 당연히 제품을 인수해야 하는 고객부터 개발해야 하는 개발책임자, 디자이너, 프로젝트 매니저, 그리고 영업까지 같이 서로 이해관계를 정리하게 된다. 그러한 과정중에 자연스럽게 많은 이야기들을 나누면서 정보를 공유하게 된다.  그러면서 제품이 개발할 수 있는 것인지 아닌 것인지 제대로 생각해보게 된다. 그것도 제품을 다 만들지 않아도 말이기 때문이다. 

 사실 "아니, 애자일한 방법을 쓰는 것은 당장 문서를 안적고 그냥 해보는 것 아닌가?". "코딩이 논쟁을 이긴다", "뭔가 보여줘야 된다 아닌다 말 할 수 있지 않을까?" 등등의 이야기를 하는 사람들이 많다. 이러한 분들이 이렇게 생각하는 것, 이해한다. 당연한 일이다. 나는 지금 문서를 처음부터 다 만드는 Waterfall 방식을 이야기 하는 것이 아니다. 이 점은 분명하다. 나는 문서조차 반복적으로 애자일하게 만들어야 한다고 생각한다

 즉 '문서작성->구현->검증'을 반복하는 것은 매우 매우 당연한 일이다. 하지만 그것 이전에 정말 우리가 만들어야 하는 것을 생각해보는 일 자체는 어떤 범죄나 반역행위는 아니다. 그러니 지나치게 놀라거나 화를 내지 말았으면 좋겠다.

 조엘 스폴스키가 이미 말했듯이 실제 제품이 구현된 상태에서 변경사항이 발견되어서 코드를 고쳐야 하는 고통보다는 그냥 문서조각에 적혀있는 글 좀 바꾸는 것이 덜 고통스럽다. 그래서 문서를 적자는 것이다. 

  다시 한번 요리를 만드는 과정에 빗대어 이야기를 해보고자 한다. 만약 요리사가 스테이크 풀코스 요리를 준비해서 냈는데 음식을 먹는 손님이 이가 너무 안좋은 사람이라 고기를 씹을 수 없거나 채식주의자가 온다면 어떻게 하곘는가? 그러한 정보를 전달해 주지 않은 가게 총지배인을 욕해봐야 이미 늦은 것이다. 진짜 훌륭한 장군이라면 전쟁 전에 승리를 해야 한다는 손자의 가르침은 이를 말 하는 것이다.


GUI specification은 어떻게 써야 할까

  이 문서는 PM(프로젝트 관리자)가 유지/보수를 담당하는 문서이다. 이 제품을 이용해서 고객을 만족시키고 사업을 성공적으로 만들 방법을 고민해야 한다. 디자이너나 개발자가 작성에 참여할 수 있지만 최종적으로는 고객을 대응하는 방식을 결정하기 때문에 PM이 이것을 다루어야 한다. 

 이 문서를 읽고 나서는 “아, 이 소프트웨어는 이렇게 쓰면 되겠구나”라는 생각이 들어야 한다. 이게 핵심이다. 

 문서 서식을 적는 방법은 그다지 도움이 될 것 같지 않다. 자칫 100여장의 거대한 종이 뭉치를 누군가에 던져주라고 하면 그것은 정말 마땅한 방법이 아니다. 그러므로 이렇게 적어보면 좀 이해가 빠를 것 같이 적어본다. 

 꼭 해보면 좋은 일
  1. Mindmap을 그려본다. 의외로 많은 생각을 손쉽게 정리하게 해준다.  
  2. 그린  Mindmap을 가지고 고객들을 만나서 피드백을 받아보고 또 수정한다. 
  3. 종이에 실제 돌아갈 앱/웹페이지를 WireFrame(실제 화면을 선만으로 그려서 중요한 화면을 구성하는 요소가 무엇인지 보여주는 그림)을 손으로 그리고 흐름을 만들어 보여준다.
  4. 당장은 잘 그린 그림이 아니라 스케치 수준의 그림이라도 그냥 카메라로 찍거서 붙인다. 그림을 수정하기 위해서는 그냥 칠판에 다시 그려서 사진찍어 붙인다. 
  5. 처음에는 표지 빼고 10 page분량만 적어라. 가장 핵심적인 것만 적을 수 밖에 없을 것이다. 그리고 이것을 개발을 포함한 첫번째 iteration을 마칠 때까지 유지한다.

꼭 하지 말아야 하는 일 
  1. 그냥 한줄로 일필휘지로 혼자 골방에 처박혀 적는다. 
  2. 고객이 뭘 알겠나 나 혼자 오탈자 없는지 한번 본다. 
  3. 자세히 자세히 무조건 자세히 적는다. 
  4. 그림은 반드시 제대로 해야 한다 생각하므로 무조건 포토샵으로 작업해야 한다.
  5. 한번에 100 page나 된 문서를  전 팀멤버들에게 보낸다. 그리고 “내일까지 리뷰해달라” 메일 보낸다.  


Software design specification은 어떻게 써야 할까?

 이 문서는  CTO(기술책임이사)나 Technical leader(기술 수석)가 유지/보수를 담당하는 문서이다. 이 제품을 이용해서 이 제품이 어떠한 제품이 되어야 하는지 설계안을 담고 있어야 한다. 다른 역할을 가지고 있는 사람도 있어야 하지만 기술에 관련된 사람들이 참고하는 문서가 되어야 한다. 

 이 문서를 읽고 나서는 “아, 이 소프트웨어는 이렇게 구현하면 되겠구나.”라는 생각이 들어야 한다. 이게 생각이 안나면 잘못된 문서다. 

 이것 역시 문서 서식을 적는 방법은 그다지 도움이 될 것 같지 않다. 그래서 하면 좋은 일/하지 말아야 할 일로 구분해서 적어본다. 

 꼭 해보면 좋은 일
  1. 각 모듈들의 계통/개념등을 Mindmap을 그려본다. 의외로 많은 생각을 손쉽게 정리하게 해준다.  
  2. 그린  Mindmap을 가지고 고객들을 만나서 피드백을 받아보고 또 수정한다. 
  3. 각 모듈들에 대해서 어떻게 돌아가야 할지 알기 위해 가능하면 Prototype(최소한 간단하게 구현한 것들)을 먼저 하고 그것에서 얻은 경험에 의해 문서를 작성한다. 
  4. UML중에서 Sequence diagram (UML중에서 각 모듈들 간에 서로 일을 주고 받는 것에 대해 그리는 그림)을 그려본다. 그리면서 많은 문제점들을 찾을 수 있다. 물론 이 UML이 정식 양식을 다 따를 필요 없다. 이해할 수 만 있게 그려라. 
  5. 당장은 잘 그린 그림이 아니라 스케치 수준의 그림이라도 그냥 카메라로 찍거서 붙인다. 그림을 수정하기 위해서는 그냥 칠판에 다시 그려서 사진찍어 붙인다. 
  6. 처음에는 표지 빼고 10 page분량만 적어라. 가장 핵심적인 것만 적을 수 밖에 없을 것이다. 그리고 이것을 개발을 포함한 첫번째 iteration을 마칠 때까지 유지한다.

꼭 하지 말아야 하는 일 
  1. 그냥 한줄로 일필휘지로 혼자 골방에 처박혀 적는다. 
  2. 고객이 뭘 알겠나 나 혼자 오탈자 없는지 한번 본다. 아무도 보여주지 않는다. 
  3. 문서로 먼저 적고 머리로만 생각한다.  
  4. UML중에서 Class diagram(각 모듈들이 체계들을 나타낸 그림)만 그려라. 
  5. UML Drawing tool로 제대로 그린다. 하나라도 틀리면 짜증짜증 내라. 
  6. 한번에 100 page나 된 문서를  전 팀멤버들에게 보낸다. 그리고 “내일까지 리뷰해달라” 메일 보낸다.  

잊지 말아야 하는 일 - 결국 Software가 나와야 문서도 의미가 있다.

 문서를 쓰는 이유중 가장 큰것은 의사소통이다. 조금 양식이 안맞아도 좋으나 서로 생각하는 눈높이만 맞출 수 있다면 된다. 그러니 지나치게 어마어마한 것에 집착하지 마라. 긴 문서/자세한 문서를 만들려고 하지 마라. 

 이 업계에서 도는 말 중에 잊지 말아야 하는 말이 있다. “꼭 워드나 엑셀, 파워포인트 쓰는 사람들이 사고치고 컴파일러, 포토샵 쓰는 사람들이 수습한다”. 일을 벌리기만 해도 안되고 계획만 있어도 안된다. 결국 코드가 나와야 한다. 


연습 : Google 검색엔진은 어떻게 만들까? 

 자, 눈을 감고 머리로 생각을 해보자. 지금 여러분은 1995년 Stanford에 있다고 생각해보자. 그리고 ‘이제 뛰어난 검색엔진’을 만들거야 라고 생각해보자. 한번 그려보자. 


읽어볼 것들 


Comments