기능 명세서 작성 가이드

Posted on | In

.

기능명세서

이 글은 기능 명세서를 작성해야하는 이유과 그 방법에 대해 간단히 서술한 글입니다.

먼저, 기능을 정의한다는 것은 각각의 기능을 정의하고 그 기능들을 전부 합치면 하나의 서비스가 완성되어야 한다는 뜻입니다. 그렇기 때문에 해당 서비스에 들어갈 모든 기능에 대해 언급해야 한다는 점이 중요합니다.

이는 결국 기능 명세서는 completeness를 가져야 한다는 말과 같습니다.

그러나 이에 대해 이해를 하고 있더라도 막상 기능명세서를 쓰려고 보면 다음과 같은 두 가지 내용에서 막막함을 느낍니다.

  1. Level of Detail
  2. How to list up?

Level of Detail

어느 정도로 세분화시켜서 기술 명세를 써야하는 지에 대한 것에는 많은 논쟁이 있을 수 있지만, 널리 쓰이는 방법론에 대해 언급하자면 유닛 테스트가 가능한 단위로 나누는 것입니다. 이렇게 나누게 되면 너무 상세하게 기술해야하는 것들이 많아지는 것이 아니냐는 생각을 하실 수 있지만, 실제로 제대로 된 기술 명세서는 100개 이상의 명세가 나오곤 합니다.

여기서 왜 하필 유닛 테스트가 가능한 수준으로 명세하는 지 궁금하실텐데요. 기술 명세를 이 정도 상세하게 적어놓으면 좋은 점이 많기 때문입니다.

  1. 기술명세서를 가지고 곧바로 구현으로 들어갈 수 있다.
    • 이미 명세 수준이 유닛 테스트 레벨로 내려가 있기 때문에 이 명세를 따라서 구현을 해나가면 하나의 서비스가 완성되게 됩니다.
  2. 기술명세서를 테스트 케이스 및 문서로 활용할 수 있다.
    • 기술명세서가 이미 유닛 테스트 레벨로 적혀있기 때문에 이 자체가 테스트 항목이 될 수 있습니다.
  3. 기술명세서를 유지보수에 쉽게 이용할 수 있다.
    • 기술명세서를 이용해서 유지보수에 유용하게 사용할 수 있습니다.

How to list up?

그렇다면 이제 어느 정도 상세하게 적어야하는 지 이해를 했다면 그 리스트를 어떻게 세워야 하는 지도 궁금할텐데요. 다음과 같은 단계를 거쳐서 접근하면 좀 더 쉽게 접근할 수 있습니다.

  1. 용어 정의

먼저 해당 서비스에 들어가는 용어를 정의하는 과정이 필요합니다. 실무를 진행하다보면 같은 기능 및 컴포넌트를 가리키면서도 서로 다른 용어를 사용하는 경우가 많기 때문에 이에 대한 용어 통합 및 정의가 먼저 필요합니다.

  1. 기능 계층화

기능을 크게 대, 중, 소 세 단계로 나눠서 계층화 시키는 것이 좋습니다.

  1. 말의 어미

계층화된 기능을 명세하는 경우에는 말의 어미를 다음과 같은 방식으로 마무리 한다면 좀 더 쉽게 작성할 수 있습니다.

  • ~ 하여야 한다.
  • ~ 할 수 있어야 한다.
  1. Error case

기능 명세를 하다보면 정상 작동 케이스만을 명세하는 경우가 많은데 에러 케이스에 대한 방어 로직 등도 하나의 기능이므로 정상 케이스를 기반으로 2개 이상의 에러 케이스(기능)들을 생각해나가는 방식으로 접근한다면 좀 더 쉽게 접근할 수 있습니다.

Tips

사실 모든 프로젝트를 진행함에 있어 이와 같은 기술 명세를 작성하지도 않고, 자세한 정도가 상이할 수 있습니다. 그래서 많은 경우에 생략하기도 하고 조금 상세의 정도를 낮추기도 하는 데요. 다음과 같은 포인트에서 상세의 정도를 낮춘다면 좀 더 쉽게 작성할 수 있습니다.

  • Level of Detail을 대, 중과 같이 2가지 단계로만 나눔.
  • 정상 케이스 하나당 모든 에러 케이스(기능) 및 방어 로직(기능)을 명세하는 것이 아니라 중요한 에러 케이스만 다룸.

구조설계서

이 글을 읽으시면서 그러면 무엇에 대한 기능 명세를 작성해야 하는 생각이 드셨다면 매우 올바른 접근을 하고 계신겁니다. 보통 기능 명세를 쓰기 쉬운 경우는 UI가 존재하는 웹프로젝트와 같은 경우인데요. 다른 서비스에 있어서도 그 역할을 해주는 구조설계서가 필요합니다. 즉, 기능명세서를 쓰기 위해서는 구조설계서가 필요한 것입니다.

구조설계서는 보통 그림이 위주(Infographic)입니다. 또한, 다음과 같은 내용들을 포함합니다.

  1. System definition
  • System definition이란 하나의 시스템(서비스)를 구성하고 있는 subsystem들과 그 시스템들 간의 연결점이 되는 Interface들을 포함하는 것입니다.
  1. Physical distribution(Deployment)
  • System definition에서 구성한 서브시스템들이 실제로 어떤 서버에 어떻게 배치되어 있는 지를 기술하는 부분입니다.
  1. Usecase Workflow
  • 실제 유즈케이스들이 어떻게 흘러가는지 그 워크플로우를 기술하는 부분입니다.

Conclusion

사실 문서를 작성하는 것이 쉽지 않고 특히나 개발자의 측면에서 쉽지 않은 작업이라 생각합니다. 그러나 문서를 작성함을 통해서 협업 및 여러 측면에서의 장점을 취할 수 있다는 점에서 이와 같은 문서 작성법을 익혀놓는 것은 좋다고 생각합니다. 다만, 이런 전통적인 기능 명세서 및 구조 설계서는 최근 대두되고 있는 블록체인이나 딥러닝 프로젝트에서는 완벽하게 들어맞지 않는다는 점에서 이와 같은 프로젝트들에는 어떤 식으로 문서를 작성하면 좋을지 꾸준히 공부해 나갈 예정입니다.

.