목적
학교에서 아이디어 페스티벌 프로젝트를 진행하면서 기능 명세서를 작성 해봤습니다.
처음에 작성할 때는 어떻게 작성해야 하는지도 모르겠고 막막 했기 때문에 선배들의 자료를 참고하거나 인터넷에서 찾아보며 작성 해봤습니다.
그러면서 기능 명세서 작성법을 글로 정리해두면 좋을거 같아 작성하게 되었습니다.
작성법
기능 명세서
기능 명세서란?
소프트웨어 제품이 사용자에게 어떤 기능을 제공할 것인지, 어떻게 동작해야 하는지 상세하게 기술한 문서이다.
기능 명세서는 제일 중요한 역할을 합니다.
왜냐하면 디자이너는 우리가 작성한 기능 명세서를 기반으로 디자인을 진행하기 때문입니다.
만약 기능 명세서를 정확히 작성 하지 않으면, 디자이너는 의도를 이해하지 못하거나 자기 방식대로 디자인할 수 있으며, 그 과정에서 불필요한 의견 충돌이 생길 수도 있습니다.
그럼 기능 명세서는 어떻게 작성해야 할까요?
1. 기능은 명확하고 짧게 작성한다.
내가 작성하려는 기능이 어떤 역할을 하는지 한 문장으로 정리하면 좋습니다.
예를 들어 "사용자는 학교 이메일을 통해 회원가입 할 수 있다."
이렇게 짧고 명확한 정의를 작성하면 불필요한 설명은 제거하고 핵심 기능을 빠르게 전달할 수 있습니다.
2. 사용자 시나리오를 구제척으로 작성한다.
단순히 "버튼을 누르면 다음 화면으로 이동한다" 같은 설명이 아니라,
실제 사용자가 어떤 흐름으로 기능을 이용하는지 스토리텔링 방식으로 작성하면 효과적으로 작성 할 수 있습니다.
에시)
-사용자는 회원가입 버튼을 클릭한다.
-이메일, 비밀번호를 입력한다.
-이메일 인증을 완료하면 회원가입이 완료된다.
이렇게 작성하면 더욱 쉽게 이해 할 수 있습니다.
3. 화면 설계를 첨부한다.
기능 명세서에는 화면 설계도(와이어 프레임)가 반드시 포함되어야 합니다.
텍스트로만 설명하면 오해가 생길 가능성이 크기 때문에 figma 같은 툴을 활용 해 기본적인 화면 설계를 공유하는 방법도 효과적입니다.
4. 입력값과 출력값을 명확히 정의한다.
데이터 정의는 기능 명세서에서 핵심적인 부분입니다.
사용자가 입력하는 값과 그에따른 시스템의 출력 결과를 표로 정리하면 훨씬 이해하기 쉽습니다.
5. 예외 처리를 작성한다.
예외 상황을 기능 명세서에 작성하지 않으면 디자이너는 기본 기능만 구현하고 넘어갈 수도 있습니다.
그러면 이후 QA 단계에서 문제가 발생할 가능성이 커집니다.
예외 처리 예시)
-이메일 형식이 잘못된 경우: "올바른 이메일을 입력하세요"
-비밀번호 형식이 다른 경우: "비밀번호는 최소 8자 이상이어야 합니다"
이렇게 예외 상황을 꼭 명시해서 작성 해주어야 합니다.
여기까지 제가 알려드리는 기능 명세서 작성시 꿀팁이고, 다음은 API 명세서 작성법에 대해 알려 드리겠습니다.
API 명세서
API 명세서는 백엔드 직종이 작성 하지만 알아보면 좋을 것 같아서 작성합니다.
API 명세서란?
API 명세서는 클라이언트(앱, 웹 등)와 서버가 데이터를 주고받을 때 어떤 규칙으로 요청·응답할지를 정리한 문서이다.
API 명세서에 포함되는 기본적인 요소들을 알아보겠습니다.
메서드(Method)
메서드는 요청 방식을 뜻하며 GET, POST, PUT, PATCH, DELETE 다섯개가 있습니다.
먼저 GET은 데이터 조회, POST는 새로운 데이터 생성, PUT은 데이터 전체 수정, PATCH는 데이터 부분 수정, DELETE는 데이터 삭제를 의미합니다.
API 명세서에는 이 각 기능들의 메서드 방식을 표시해야 합니다.
엔드 포인트(Endpoint)
엔드 포인트는 클라이언트가 요청을 보낼 때 접근하는 API 주소(URL)를 의미합니다.
쉽게 말해 어떤 기능을 호출할지를 구분하는 위치 정보라고 할 수 있습니다.
예를 들어 /api/users/signup 은 회원가입을 처리하는 엔드 포인트이고, /api/users/signin 은 로그인을 처리하는 엔드 포인트 입니다.
요청 데이터
요청 데이터는 클라이언트가 서버로 보내는 정보입니다.
URL, 경로 변수, 헤더, 본문 등 여러 방식으로 전달될 수 있습니다.
예를 들어 회원가입에서 이메일과 비밀 번호가 요청 데이터가 됩니다.
이에 대해 서버가 돌려주는 결과가 응답 데이터 입니다.
보통 JSON 형식으로 반환되며, 요청이 성공했는지 실패했는지를 알려주고 필요한 데이터를 함께 제공 합니다.
{
"status": "error",
"message": "올바른 이메일 형식을 입력하세요."
}상태 코드
상태 코드는 요청 처리 결과를 숫자로 표현하는 HTTP 표준 코드입니다.
200 OK→ 성공201 Created→ 새 데이터 생성 성공400 Bad Request→ 잘못된 요청 (입력값 오류 등)401 Unauthorized→ 인증 실패403 Forbidden→ 권한 없음404 Not Found→ 요청한 리소스 없음500 Internal Server Error→ 서버 내부 오류
이런식으로 나타낼 수 있습니다.
이상으로 명세서 작성법과 꿀팁에 대해 알아보았습니다.
이 글을 읽고 명세서 작성하는데에 도움이 되었으면 좋겠습니다.
감사합니다
