기능 명세서 작성 요령

소프트웨어 개발 실패시 중요항목으로 작용

 

소프트웨어 프로젝트는 낮은 품질과 지연되는 일정, 초과되는 예산으로 악명 높다. 소프트웨어 위기(Software Crisis)라고도 불리는 이런 현상의 원인에는 항상 불완전하거나 잘못된 요구사항이 있다. 스탠디시 그룹(Standish Group)이 352개 기업의 8000개 프로젝트를 조사한 결과에 따르면, 소프트웨어가 실패하는 주요인으로 사용자의 참여 부족(12.8%), 불완전한 요구사항과 명세서(12.3%), 변화하는 요구사항과 명세서(11.8%) 등 요구사항과 관련된 항목이 거의 40%에 달함을 알 수 있다. 이번 호에서는 요구사항과 관련된 최소한의 문서인 기능 명세서(Functional Specification)에 대해 알아보자.

 

서광열 | kwangyul.seo@gmail.com

 

요구사항이란?

 

소프트웨어 프로젝트에 있어 요구사항 분석이란 무엇을 하는 소프트웨어를 만들지 결정하는 단계이다. 실제로 많은 소프트웨어 프로젝트가 무엇을 만들지도 확실히 결정하지 않고, 코드를 작성하고 테스트를 수행하는 모습을 볼 수 있다. 이런 일을 잘할수록 슈퍼 프로그래머로 불리고 칭송 받는 게 현실이다. 하지만 이렇게 작성된 소프트웨어는 최종 사용자가 실제로 원했던 모습이 아니며, 잘 만든 소프트웨어일수는 있어도 결국 쓸모없는 소프트웨어가 된다.

요구사항을 작성하는 목적은 다양하다. 소프트웨어의 설계와 구현뿐만 아니라, 프로젝트의 범위 확정, 비용 측정, 일정 관리, 문서화와 교육 훈련 등 다양한 제반 활동을 지원하는데 있어 요구사항 작성과 관리는 빠질 수 없는 중요한 활동이다. 이처럼, 요구사항은 개발팀뿐만 아니라 해당 소프트웨어와 이해관계를 함께 하는 모든 사람들이 참여하는 중요한 활동이다.

요구사항 분석 단계에서 나오는 최종 산출물은 요구사항 명세서이다. 요구사항 명세서에 포함되는 내용은 무척 다양하다. 시스템의 목표, 독자, 전체 기술 요약, 프로젝트 제약 조건 등이 서론으로 포함되고, 본문에는 기능 명세의 필요에 따라 자료 흐름도(Data Flow Diagram)이나 프로세스 명세서(Process Specification), ERD (Entity-Relationship Diagram) 등이 포함되기도 한다. 또한 표준, 법률 등에 의한 외부 규제나 성능 관련 내용을 포함한 비기능 요구사항(Non-functional Requirement), 프로젝트가 완료되었을 때의 검증 기준 등도 문서에 포함된다.

하지만 중소규모의 프로젝트에서는 이런 요구사항 문서 작성이 부담인 경우가 많으며, 압도적인 문서의 양에 겁먹어 사실상 아무런 문서화를 하지 않는 경우가 비일비재하다. 현재도 중소기업 간의 소프트웨어 계약에서는 시스템을 요약적으로 기술한 1-2장의 짧은 문서가 요구사항 명세서를 대신하는 경우가 많으며, 이런 명세서의 모호한 구절은 이후 프로젝트의 범위와 종료 여부를 놓고 논쟁의 대상이 된다.

 

기능 명세서

 

기능 명세서는 앞서 언급한 요구사항 명세에 들어갈 내용 중에 하나이며, 소규모 프로젝트에서는 사실상 기능 명세서만 제대로 작성되어도 프로젝트를 성공적으로 이끌 수 있다. 여기서 말하는 소규모란 개발자 1명이 일주일 이상 개발해야 하는 복잡도를 가진 모든 소프트웨어를 통칭한다. 1명의 개발자가 하루 이틀 작성하는 미니 프로그램을 제외한다면, 모든 소프트웨어는 명세 없이는 항상 일정을 초과하고 품질이 낮은 소프트웨어를 만들 수밖에 없다.

그렇다면 기능 명세란 무엇인가? 기능 명세란 1) 사용자의 관점에서 2) 최종 제품이 3) 어떤 모습이며 4) 어떻게 동작할 것인지를 기술한 문서를 말한다. 기능 명세란 어디까지나 최종 사용자의 입장에서 기술한 문서이기 때문에 내부 구현이나 설계 이슈를 포함하지 않는다. 또한 최종 제품에 대해서 이야기하기 때문에 각 소프트웨어 컴포넌트들이 어떻게 상호 작용하는지도 중요하지 않다. 그저 이 프로젝트가 끝나면 나오는 최종 산출물이 어떤 모습이며 어떤 일을 수행하는지를 자세히 기술하는 것이다.

실제로, 많은 개발자들이 무엇을 만들 것인지와 어떻게 만들 것인지를 혼동한다. 무엇과 어떻게 사이에 명확한 경계가 존재하지는 않지만, 소프트웨어 요구사항도 파악하기 전에 설계가 시작되어서는 곤란하다. 최종 소프트웨어가 어떤 모습인지를 확실하지 않은 채 UML을 이용해 클래스 다이어그램부터 그리고 있어서는 곤란하다. 이런 시스템은 필연적으로 주객이 전도되어 설계가 요구사항의 변경이나 삭제를 요구한다. 기능 명세는 ‘무엇’을 만들 것인지를 분명히 하는 문서라고 보면 된다.

개발자 입장에서 기능 명세는 개발 과정에서 궁금할 수 있는 모든 질문에 답을 해놓은 문서가 존재한다는 뜻이다. 또한 명세는 고객 혹은 최종 사용자의 승인을 받은 문서이므로, 명세만 따라서 만들면 고객이 실제로 원하는 소프트웨어를 작성할 수 있다는 장점이 있다. 또한 분쟁의 소지가 생겼을 때는 결국 명세에 명시된 내용을 근거로 판단을 내릴 수 있다 (물론 상당수의 소프트웨어 프로젝트에 명세는 무시되고, 고객의 머릿속에 있는 요구사항이 최우선이긴 하지만 말이다).

종종 기능 명세를 기술 명세(Technical Specification)와 혼동하는 경우가 있다. 기술 명세는 프로그램 내부 구현에 대한 기술이며, 데이터 구조, 관계형 데이터베이스 모델, 프로그래밍 언어, 알고리즘, 플랫폼 등을 기술하는 것이 일반적이다. 기술 명세는 설계 및 구현에 직접적인 도움을 주기 위한 것이며 사용자의 관점에서 시스템을 기술한 기능 명세와는 다르다.

쉽게 커뮤니케이션이 가능한 10명 이하 소규모 개발 조직에서는 대부분의 의사소통이 구두로 이루어지므로, 기술 명세를 생략하는 경우가 많지만 기능 명세는 개발팀만을 대상으로 하지 않는다는 면에서 여전히 유효하다.

 

기능 명세에 들어갈 내용

 

기술 명세의 중요성을 설파하고 나면, 기술 명세의 템플릿을 원하는 분들이 많다. 기술 명세를 한 번도 작성해 본 적이 없는 분들의 입장에서 템플릿은 기술 명세 문서를 작성하는 단서가 되기도 하지만, 무비판적으로 모든 템플릿의 항목을 채우려는 문서화 노력은 보통 불필요한 노동으로 끝나는 경우가 많다.

기술 명세는 프로젝트 성격에 따라 달라지지만 일반적으로 다음 요소들은 반드시 포함되며 추가 설명이 필요 없을 정도로 자세히 기술되어야 한다.

 

1) 시나리오

 

기술 명세는 사용자 관점에서 시스템을 바라본 것이므로, 이를 가장 잘 기술하는 방법은 실제 사용자를 가정하고 시스템을 어떻게 쓸 것인지 시나리오를 작성해 보는 것이다. 예를 들어, 온라인 영어 학습 사이트에 대한 기술 명세를 쓴다고 하면, 성적은 중위권이며 방과 후에 PC방에서 게임하는 것이 취미인 15살 박 모 군과 같이 구체적인 인물을 설정하고, 이런 인물이 영어 학습 시스템을 사용할 때 어떤 패턴을 보일 것인지를 기술하는 것이 효과적이다.

이때 시나리오는 유스 케이스(Use Case)가 될 수도 있고, 조금 더 단순화된 형태인 유저 시나리오(User Scenario)가 될 수도 있다. 소프트웨어 방법론이나 프로젝트의 성격에 따라 어떤 방식을 선택해도 무방하다. 하지만 원칙은 시스템의 모든 기능을 한 번 이상을 이용할 수 있도록 충분히 많은 시나리오를 작성해서, 개발자가 시스템을 설계할 때 전혀 고려된 적이 없는 상황을 마주치는 일이 생기지 않도록 해야 한다.

기능 명세의 시나리오는 무엇을 테스트해야할지 단서를 제공한다는 측면에서 소프트웨어 테스트나 품질보증(Quality Assurance, QA) 팀에게도 소중한 문서이다. 특히 시스템의 기능 테스트(Functional Test)는 유저 시나리오에 바탕을 뒀을 때 가장 효과적이다. 유저 시나리오는 최종 제품이 원래 요구사항에 기술된 요소를 모두 충족시켰는지를 판단하는 중요한 근거가 되기 때문이다.

2) 세부사항

 

기능 명세를 작성함에 있어서는 세부사항이 무척 중요하다. 특히, 무엇인가 잘못될 수 있는 경우 모든 가능성에 대해서 꼼꼼히 명세를 작성해야 한다. 예를 들어, 전자상거래 웹페이지의 로긴 페이지를 만든다고 한다면 다음과 같은 이슈를 모두 고민해야 한다.

1) 등록되지 않는 ID로 로긴한 경우?
2) 등록된 ID지만 패스워드가 틀린 경우?
3) 같은 ID에 3번 이상 다른 패스워드를 입력했을 경우 추가적인 로그인 시도를 금지할 것인가?
4) 아이디와 패스워드를 잃어버린 사람이 이를 되찾는 방법은?
5) 패스워드 관련 힌트를 제공할 것인가?
6) 한 번 로긴한 후에는 얼마나 오래 세션이 지속되는가?

세부사항을 작성할 때, UI를 중심으로 기능을 기술하는 것이 가장 효과적이다. 특히, 웹개발의 경우 각각의 페이지를 기준으로 소프트웨어가 어떻게 동작하는지 설명하는 방법이 일반적이다. 모든 페이지에 고유의 이름을 붙이고, 각 페이지에서 나오는 메뉴와 UI 위젯이 어떤 역할을 하는지 구체적으로 기술한다.

3) 열린 이슈

 

명세를 작성하는 목적은 프로젝트 시작 전에 최대한 많은 요구사항을 끌어내고 최종 산출물의 모습을 파악하는 데 있지만, 필연적으로 일부 문제들은 미해결 상태로 남아있게 된다. 이런 부분은 기능 명세에 분명히 기술하여 프로젝트가 진행

되면서 해결해 나가야 한다.

 

변경 추적

 

기능 명세뿐만 아니라 모든 개발 관련 문서의 생명은 얼마나 변경 추적이 잘 되느냐에 달려 있다. 명세와 관련된 가장 큰 불만은 명세를 작성한 이후 프로젝트 요구사항이 변화하고 설계 및 코드에 수정이 일어남에도 불구하고 명세가 갱신되지 않는다는 데에 있다. 따라서 개발자들을 비롯한 이해 관계자들은 명세를 신뢰하지 않게 되고, 쓸모없다고 생각하게 된다.
특히 요구사항 분석, 설계, 구현, 테스트, 유지 보수를 한 번씩만 거치는 폭포수 모델(Waterfall Model)을 따르는 조직일수록 이런 경향이 강하게 나타난다. 요구사항 분석은 프로젝트 초기에 단 한 번만 이루어지며, 이후 설계나 구현은 요구사항 변경 요청 시에 수정되지만 정작 요구사항 문서는 그대로 남는 경우이다. 이런 조직에서는 시간이 지날수록 기능 명세를 비롯한 요구사항 문서의 질은 극도로 낮아지며 유지 보수 단계에서는 누구도 기능 명세를 보지 않는 상황이 벌어진다.

 

누가 기능 명세를 쓰는가?

 

기능 명세와 관련된 가장 중요한 질문은 누가 기능 명세를 쓰느냐는 것이다. 앞서 언급한 것처럼 기능 명세는 개발팀뿐만 아니라, 마케팅, 문서화팀, QA팀 등 소프트웨어 프로젝트에 관련된 모든 팀이 관여하는 문서이고, 다양한 이해 관계자들을 만나서 요구사항을 끌어낼 수 있는 능력이 필요하다. 따라서 어느 정도 개발 지식이 있을 뿐만 아니라 대인 관계와 커뮤니케이션 능력이 뛰어난 사람이 명세를 작성해야 한다.

덕분에 국내에서는 기능 명세를 쓰는 사람이 개발팀장인 경우가 많지만, 훌륭한 프로그래머가 훌륭한 커뮤니케이션 능력을 갖추고 글도 잘 쓰는 경우는 국내외를 막론하고 무척 드물다. 또한 내부 구현이나 기술적인 세부 사항을 너무 잘 알고 있다는 점이 부작용으로 작용한다. 뛰어난 개발자 출신일수록 기능 명세가 아닌 기술 명세를 작성하는 경우가 많다.

기능 명세를 개발팀장이 작성하는 경우가 많은 이유는 기능 명세 작성을 개발팀 리더의 역할로 보는 관점 때문이다. 하지만 기능 명세를 작성하는 사람은 개발자나 테스터와는 다른 전문 영역으로 보는 것이 옳다. 실제로 마이크로소프트나 구글 등 대형 소프트웨어 업체는 신입 사원을 모집할 때부터 직군을 프로그램 매니저, 개발자, 테스터로 구분하고 있는데, 프로그램 매니저의 주요 역할이 요구 사항을 수집하고 기능 명세를 작성하는 데 있다.

기능 명세는 소프트웨어 요구사항의 핵심이며, 설계와 구현의 바탕이 되는 중요한 문서이다. 아직까지 기능 명세 없이 곧바로 소프트웨어를 작성하는 조직이 있다면, 기능 명세를 작성해 볼 것을 권한다. 기능 명세에 대한 더 자세한 정보가 궁금한 사람은 참고문서를 참고하기 바란다.

필자소개

---

현재 (주)노매드커넥션의 CTO로 재직 중이다. 관심 분야는 플랫폼, 가상 머신, 프로그래밍 언어 등이며 현재는 미디어 플랫폼에 많은 관심을 가지고 연구 개발을 진행 중이다. 개인 블로그인 서광열의 소프트웨어 이야기(http://skyul.tistory.com)을 통해서 소프트웨어 개발과 IT 산업에 대한 생각을 정리하고 있다.

제공 : DB포탈사이트 DBguide.net

출처 : 경영과컴퓨터 [2007년 11월호]