Joel on Software

Joel on Software   조엘 온 소프트웨어

 

한글로된 다른 "Joel on Software" 글들

영어로된 다른 "Joel on Software" 글들

필자 메일주소(영어만 사용)

 

손쉬운 기능 스펙 작성법 – 제 4부 : 효과적인 스펙 작성 요령


글 : Joel Spolsky
번역 : AhnLab
2000년 10월 15일 일요일

지금까지는  스펙이 필요한가, 스펙이란 무엇인가, 그리고 스펙은 누가 작성해야 하는가 대해 살펴보았다. 마지막으로 4부에서는 효과적인 스펙 작성 요령에 대해 가지 조언하고자 한다.

스펙을 작성하는 사람들이 이야기하는 가장 불만은 아무도 스펙을 읽지 않는다 점이다. 아무도 스펙을 읽지 않을 경우, 스펙을 작성한 사람들은 다소 냉소적인 태도를 취하게 된다. 마치 유명한 만화 딜버트 주인공처럼 엔지니어들은 두께가 4인치는 족히 될법한 두꺼운 스펙 보고서를 차곡차곡 쌓아올려 칸막이로 이용한다. 규모가 관료주의적 기업 조직에서는 모든 사람들이 달씩 따분하기 그지없는 스펙을 작성한다. 일단 스펙 작성이 완료되면, 완성된 스펙을 책꽂이 구석에 처박아 두고는 다시는 꺼내보는 법이 없다. 물론, 제품은 처음부터 스펙의 내용과는 아무 상관 없이 만들어진다. ? 아무도 스펙을 읽지 않았으니까. 스펙은 보기만해도기가질려서읽을마음이생기지않으니까. 스펙을 작성하는 과정 자체가 훌륭한 연습이 되었을 수도 있다. 스펙을 쓰기 위해서는 적어도 주어진 문제들에 대해 꼼꼼히 생각을 해봐야 하기 때문이다. 그러나, 힘들여 작성한 스펙이 책꽂이에만 꽂혀있을 읽히지도 않고 사랑 받지도 못한다는 사실은 스펙 작성자들을 허탈하게 만든다.

뿐만 아니라, 스펙이 읽혀지지 않을 경우, 제품이 완성된 많은 언쟁이 벌어지게 된다. 이를테면, 누군가가 (경영진이나 마케팅 담당자나 혹은 고객) 쫓아와서 이렇게 말할 지도 모른다. “잠깐만! 분명히 해물 찜기 만들어준다고 했잖소! 해물 찜기는 어디 있소?” 그러면 프로그래머는 이렇게 말한다. “아니죠. 스펙을 보세요. 3 4 2.3.0.1항에 분명히 해물 찜기 제외라고 명시되어 있잖아요.” 하지만, 이런 답변만으로는 고객을 만족시킬 없고 고객은 왕이기 때문에, 잔뜩 부어 있는 프로그래머는 결국 제품을 뜯어고쳐 해물 찜기를 만들어내지 않으면 된다 (이쯤 되면, 그들은 스펙에 대해 냉소적인 태도를 보일 밖에 없다). 또는, 관리자가 이렇게 말할 지도 모른다. “이봐, 대화상자에 들어가는 말이 이리 길어? 대화상자 상단에 광고를 넣어야 한단 말이야.” 그러면 프로그래머는 잔뜩 골이 나서 이렇게 말할 것이다. “스펙을보시고직접사인하셨잖아요. 대화상자의 레이아웃이며 각각에 들어갈 문장까지 스펙에 그대로 적혀있다구요!” 물론, 관리자는 스펙을 읽어보지 않았다. 읽어보려고는 했지만, 때마침 그의 작은 두뇌가 안와(眼窩) 통해 밖으로 새어나가 버렸기 때문이다. 무엇보다, 그는 화요일의 골프 약속을 지켜야만 했다.

스펙은 유용하지만, 아무도 읽지 않는다면 소용이 없다. 그러니까, 스펙을 작성하는 입장에서는 사람들이 글을 읽도록 유인하지 않으면 된다. , 누군가가 스펙을 읽으려 가뜩이나 작은 두뇌가 안와를 통해 밖으로 새어나가 버리는 일이 발생하지 않도록 세심한 노력을 기울여야 한다.

사람들이 스펙을 읽도록 유인하는 것은 대개가 글솜씨의 문제다. 그렇다고, 필자가 여기서 글솜씨를 길러라라는 말만 던져놓고 이것으로 모든 문제가 해결된다고 한다면 온당한 처사가 아닐 것이다. 그래서, 읽을만한 스펙을 작성하기 위해 반드시 지켜야 간단한 규칙을 가지 소개하려 한다.

규칙1 : 재미있게써라.

그렇다. 사람들이 스펙을 읽게끔 만들기 위한 번째 규칙은 읽는 자체가 즐겁게 만들라는 것이다. 때부터 남을 웃기는 데에는 소질이 없다는 식의 핑계는 여기서는 통하지 않는다. 누구한테나 재미있는 아이디어는 있게 마련이다. 다만, 어쩐지 재미있는 글을 전문적인 글처럼 보이지 않는다 생각 때문에 스스로 막고 있을 뿐이다. 가끔은 파격이 필요할 때도 있다.

필자가 웹사이트에 올린 여러 편의 졸작들 읽어본 독자라면, 필자의 여기저기에서 서툴지만 나름대로 재미있게 써보려고 시도한 흔적들을 발견했을 것이다. 바로 앞에서도 필자는 뇌가 새어나간다는 다소 혐오스러운 농담을 던지거나 대신 골프에 열심인 관리자를 희화화 했다. 사실, 필자의 글이 그렇게 재미있는 것은 아니지만, 그래도 필자는 열심히 노력하고 있고, 웃겨보겠다는 몸부림 자체가 우스울 수도 있다 (다소 처연하긴 하지만). 스펙을 작성하는 과정에서 재미있는 글쓰기를 시도하기에 가장 적절한 부분은 보기를 제시할 때다. 어떤 기능이 어떻게 작동되는가를 이야기해야 흔히 다음과 같이 쓰기 쉽다.

  • 사용자가 Ctrl+N 입력하여 직원이라는 테이블을 새로 만들고 직원들의 이름을 입력한다.

하지만, 같은 내용을 아래와 같이 써보면 어떨까?

  • 돼지 아가씨가 너무 통통하고 뭉툭해서 자판의 키를 하나씩 누를 수도 없는 손가락 대신 마스카라 뚜껑으로 Ctrl+N 눌러 남자친구라는 테이블을 새로 만들고 개구리 커밋이라는 이름을 입력한다.

유머작가 데이브 베리 (Dave Barry) 글을 읽다 보면, 필요 이상의 구체적인표현 글을 재미나게 만든다는 사실을 깨닫게 것이다. 가령, 그냥 라고 해도 것을 주름이 쭈글쭈글한 퍼그라고 쓰는 것이다. 그냥 사용자보다는 돼지 아가씨 재미있다. , “특수이익집단이라는 말보다는 아보카도 농사를 짓는 왼손잡이 농부들이라고 해보자. ‘공공장소에서 자기 애완견의 배설물을 치우지 않는 사람은 처벌해야 한다”’라는 말보다는 감옥에 보내서 혼자 방바닥 긁으며 외롭게 살도록 만들어야 한다라는 표현이 실감난다. 

   

혹시라도 웃기게 쓰면 전문적인 글처럼 보이지 않는다고 생각하는 독자가 있다면, 미안한 말이지만 스스로 유머감각이 없다는 사실을 인정해야 한다 (부정하려 들지 말라. 유머감각이 없는 사람들이 그런 사실을 부인한다. 필자는 속인다.) 또는,부담 없고 재미있고 읽히는 스펙을 작성한다는 이유로 사람들로부터 존경 받게 되는 분위기의 회사에서 일하고 있다면 지금 당장 다른 회사를 찾아보라. 그렇게 무자비하고 비인간적인 일터에서 시간을 허비하기에는 인생이 너무나, 너무나짧다.

규칙2 : 스펙작성은두뇌가실행할코드를저작하는것과같다.

필자는 프로그래머들이 스펙을 만들기가 어려운 이유를 다음과 같이 분석한다.

프로그래머들이 저작하는 코드의 주된 독자는 컴파일러. 물론, 사람들도 코드를 읽어야 하긴 하지만, 일반적으로 코드는 사람이 읽기엔 매우 어렵다. 대부분의 프로그래머들의 경우, 컴파일러가 제대로 읽고 올바르게 해석할 있는 코드를 만드는 것만으로도 충분히 어려운 작업이기 때문에, 사람이 읽을만한 코드를 만드는 것에 대해서까지 생각할 겨를이 없다.

번째 코드 :

void print_count( FILE* a, char  *  b, int c ){
    fprintf(a, "there are %d %s\n", c, b);}

main(){ int n; n =
10; print_count(stdout, "employees", n) /* code
deliberately obfuscated */ }


번째 코드 :

printf("there are 10 employees\n");


번째 코드나 번째 코드나 출력되는결과물은똑같다. 마찬가지로, 프로그래머들은 흔히 스펙을 다음과 같이 작성하는 경향이 있다.

사용자x 사용자의 RFC-822 형식의 이메일 주소인 ANSI 문자열 간의 매핑을 통해 정의되는 함수 AddressOf(x) 가정해 보자. 사용자A 사용자 B 있고 여기서 사용자A 사용자B에게 이메일을 보내려고 한다고 가정하자. 사용자A 다른 곳에서 정의된 특정 기술을 사용하여 신규 메시지를 발송하고자 To: 편집상자에 AddressOf(B) 입력한다.


하지만
, 똑같은 내용을 아래와 같이 써볼 수도 있다.

돼지 아가씨가 점심식사를 같이 하기 위해 개구리 커밋에게 이메일을 쓰고는 To:” 상자에 그의 주소를 입력한다

기술정보 :주소는표준인터넷주소라야한다(RFC-822 형식).


이론적으로
, 가지 보기 모두 의미 똑같다. 다만, 차이점이 있다면, 번째 보기는 꼼꼼하게 해독하지 않으면 이해하기가 힘든 반해, 번째 보기는 이해하기가 쉽다는 점이다. 프로그래머들은 무슨 학술논문처럼 보이는 스펙을 집필하려고 애쓰는 경우가 많다. 그들은 정확한 스펙을 작성하기 위해서는 기술적으로 정확하게 기술해야만 하며 그래야만 자신이 궁지에서 벗어날 있다고 생각한다.

스펙이 정확해야 뿐만 아니라, 이해할있는 것이어야 한다는 점을 간과한 것이다. 이해할 있다는 것은, 프로그래머식 표현으로 하자면, 사람의 두뇌가 컴파일 있도록 씌어져야 한다는 것을 의미한다. 컴퓨터가 인간의 두뇌와 다른 가장 차이점은 컴퓨터는 프로그래머가 나중에 사용할 용어들을 정의하는 동안에도 기꺼이 인내심을 가지고 제자리를 지킨다는 점이다. 하지만, 인간은 먼저 흥미를 자극하지 않는 , 상대방이 하는 말을 이해하려 하지 않는다. 인간들은 뭔가를 해독해야 하는 수고는 원치 않는다. 그저 있는 그대로를 읽고 이해할 있기를 원한다. 인간들을 위해서는 먼저 전체적인 그림을 제시한 후에 세부적인 사항들을 채워나가야 한다. 컴퓨터 프로그램의 경우라면, 처음부터 세부적인 것들로 시작해서 끝까지 세부적인 정보들을 채워넣을 있겠지만. 컴퓨터는 변수의 이름이 의미가 있는 것인지 따위에는 신경 쓰지 않는다. 이에 반해, 인간의 두뇌는 이야기를 들려주는 방식으로 마음 속에 구체적이고 생생한 그림을 그릴 있을 보다 효과적으로 이해한다. 설사, 그것이 이야기의 부분에 지나지 않더라도 말이다. 인간의 두뇌는 이야기를 이해하도록 진화해 왔기 때문이다.

체스를 두는 사람들한테 실제 체스 경기가 진행중인 체스판을 1초나 2 정도 보여주면, 체스판 위의 모든 말의 위치를 즉석에서 암기할 있다. 하지만, 정상적인 체스 경기에서는 없는 부조리한 방식으로 말을 움직이는 경우 (가령, 개의 () 번째 줄에 늘어놓는다거나, 검정 비숍을 모두 검정색 칸에 올려놓는다거나 하는 식으로), 말의 위치를 기억하기가 어려워진다. 이것은 컴퓨터가 사고하는 방식과는 전혀 다르다. 체스판을 기억할 있도록 개발된 컴퓨터 프로그램이라면, 말들이 규칙에 맞게 놓여있든 그렇지 않든 암기 난이도는 똑같을 것이다. 하지만, 인간의 두뇌가 작동하는 방식은 컴퓨터와 같은 랜덤 액세스 방식이 아니다. 인간의 두뇌에서는 경로가 강화되는 경향이 있고, 보편적인 논리를 가진 것은 그렇지 않은 것보다 쉽게 이해된다.

그러므로, 스펙을 작성할 때는 스펙을 읽게 독자를 상상해 보고 단계마다 그들에게 무엇을 이해하도록 요구하고 있는지 상상해 보라. 문장 문장을 내려갈 때마다, 문장을 읽는 사람이 내용을 원래의 맥락대로 정확하게 이해할 있을 것인지를 스스로 자문해 보라. 스펙을 읽게 독자 중에 RFC-822 무엇인지 모르는 사람이 있다면, 이것이 무엇인지 용어정의를 일러주든가, 아니면, 최소한 RFC-822 대한 언급을 기술 정보라는 이름 하에 주석으로 처리하여, 높은 사람들이 기술적인 전문 용어들 때문에 스펙 읽기를 포기하는 일이 없도록 해야 한다

규칙3 : 최대한쉽게써라.

쉬운 문체로 쓰면 어쩐지 비전문적인 글처럼 보인다는 편견 때문에 현학적이고 딱딱한 용어들을 사용해서는 된다. 가능한 쉬운 말을 써라

사람들은 그냥 쓰다라고 해도 것을 굳이 이용하다라고 한다. “쓰다 어쩐지 비전문적으로 보이기 때문이다. (“비전문적이라는 말이 나왔다. 누군가가 그것이 비전문적이라는 이유로 어떤 일을 못하게 한다면, 이미 실질적인 논쟁 주제에서 벗어난 이야기를 하고 있는 것이다.) 실제로, 쉽고 명료하게 쓰면 무언가 잘못된 것이라고 생각하는 사람들이 적지 않은 같다.

문장은 짧은 문장으로 나눠서 쓴다. 문장을 명료하게 쓰는 것이 어렵다면, 이를 혹은 개의 짧은 문장으로 나눠서 쓰면 된다

페이지 전체를 텍스트로만 빽빽하게 채운 활자의 장벽은 피하라. 사람들이 지레 겁을 먹고 읽으려 들지 않는다. 신문이나 잡지에서 전체를 활자로만 가득 채운 경우를 적이 있는가?

잡지의 경우, 그림이 들어가는 페이지에는 가운데 큼직한 활자체로 본문에서 따온 인용문을 싣는다. 읽기에 빡빡하다는 느낌을 주지 않기 위해서다. 표나 그림, 그래프 충분한 여백을 이용하여, 독자에게 만만해 보이도록 만들어라.

"잡지의 경우, 그림이 들어가는 페이지에는 가운데 큼직한 활자체로 본문에서 따온 인용문을 싣는다. 읽기에 빡빡하다는 느낌을 주지 않기 위해서다."

눈에 들어오는 스펙을 작성할 있는 가장 좋은 방법은 화면 그림을 많이 활용하는 것이다. 그림 하나가 마디 말을 대신할 있다. Windows 소프트웨어에 대한 스펙을 작성해야 한다면, Visual Basic 설치하고 최소한 화면 샘플을 만들 있을 정도로는 익혀두자. (Mac 운영체제의 경우에는 REAL Basic, 페이지의 경우에는 Front Page Dreamweaver 사용한다). 그런 다음 만들어진 화면 그림을 스펙에 붙여넣으면 된다 (Ctrl+PrtSc).

규칙4 : 여러다시읽고재검토하라.

원래는 4 규칙에 대해 길게 해설을 늘어놓을 계획이었지만, 규칙은 너무 간단명료한 것이라 설명이 필요 없을 같다. 그대로, 작성된 스펙을 여러 다시 읽고 재검토하라. 모든 문장은 극도로 이해하기 쉬워야 한다. 그렇지 않은 문장이 눈에 띄거들랑 다시 써라.

4 규칙에 대한 설명을 줄여서 시간을 절약했으니까 규칙을 하나 추가해야겠다.

규칙5 : 표준서식은잊어라.

스펙을 작성할 때마다 적용할 표준 서식을 만들고 싶은 유혹을 이겨내야 한다. 언뜻, “모든 스펙이 똑같은 통일된 형식을 갖추는 중요하다고 느껴질지도 모른다. 하지만, 사실은 그렇지 않다. 형식을 통일한다고 달라질 것이 뭐가 있나? 책장에 꽂혀있는 책이 전부 똑같이 생겼는가? 아니, 똑같이 생기기를 바라는가?

표준 서식을 만들 경우, 심각한 문제는 기능마다 중요하다고 생각되는 항목들을 잔뜩 추가하게 가능성이 높다는 것이다. 가령, 회장님이 지금부터는 Microsquish 모든 제품에 인터넷 컴포넌트 포함되어야 한다는 명을 내리셨다고 치자. 이제 Microsquish 엔지니어들은 스펙을 작성할 때마다 항상 인터넷 컴포넌트라는 항목을 포함시키지 않으면 된다. 그것이 아무리 간단한 스펙일지라도. 하다못해 Microsquish 키보드에 대한 스펙을 만들 때조차도 인터넷 컴포넌트를 포함시켜야 한다 (이후, 사람들은 어느날 갑자기 키보드에 쓸모도 없는 인터넷 쇼핑 버튼이 등장하게 되었는지를 궁금해 하게 것이다).

이런 항목들이 자꾸 늘어갈수록, 스펙 서식의 분량도 점점 커진다. (여기, 아주 아주 나쁜 스펙 서식의 예를 제시했으니 참조하기 바란다. 도대체 스펙에 참고문헌 필요하단 말인가? 용어집 뭐고?) 스펙 서식의 분량이 늘어나면, 사람들은 스펙 작성을 더욱 기피하게 된다. 스펙 작성 자체가 어마어마한 일처럼 보이기 때문이다.

스펙은 사람들에게 읽혀져야 문서다. 사람들이 읽기를 바라고 글이라는 점에서 스펙은 뉴요커() 대학신문에 기고하는 글과 다르지 않다. 대학교수가 대학신문에 실을 글을 주문하면서 학생들에게 표준 서식을 나눠주고는 서식에 칸칸이 맞춰서 글을 쓰도록 하는 것을 적이 있는가? 표준 서식에 맞춰서 똑같은 형식으로 작성된 사설을 적이 있는가? 표준 서식에 대한 생각일랑 아예 버려라.



이 기사는 영어로 Painless Functional Specifications Part 4 라는 이름의 기사가 원본입니다. 

Joel Spolsky는 뉴욕에 위치한 작은 소프트웨어 회사인 Fog Creek Software의 창업자입니다. 예일 대학교를 졸업하고 Microsoft, Viacom, Juno등에서 프로그래머와 매니저로 일했습니다.


이 페이지의 내용은 한사람의 의견을 대변합니다.
All contents Copyright ©1999-2005  by Joel Spolsky. All Rights Reserved.

FogBUGZ | CityDesk | Fog Creek Software | Joel Spolsky