소프트웨어 문서

SRS (Software Requirements Standards, 요구사항명세서)

 

소프트웨어가 만족해야하는 요구사항을 상세하게 명세한 문서

• 작성에 필요한 조치들
  • 이해관계자들이 반드시 참여해야합니다.
  • 비전공자도 이해할 수 있도록 언어를 정의하고 부록을 포함하여야 합니다.
  • 소프트웨어 개발을 주도하는 기술진들도 반드시 참여야해야합니다.
  • 여러가지 비용이 현실적으로 고려되어야합니다.
  • 소프트웨어 개발방법론에 따라 문서는 항상 최신상태를 유지합니다.
  • 국제 및 국내 표준을 따르도록 기획합니다.
• SRS에 담겨야하는 내용 예시
  • 소프트웨어 개요
    • 개발하고자하는 소프트웨어의 전반적인 내용을 요약
      • 소프트웨어의 소개
      • 소프트웨어의 목적
      • 주 사용자에 대한 설명
  • 유저 시나리오
    • 사용자가 해당 소프트웨어를 사용하기 위한 일련의 과정
      • 목표 시나리오: 개발자의 의도대로 목표까지 사용되는 시나리오
      • 경험 시나리오: 사용자가 실제 소프트웨어를 사용하며 생성되는 여러가지 과정
  • 와이어프레임
    • UX를 고려하여 만든 UI로 각 인터페이스가 어떤 역할을 하는지, 대략적인 모양, 색깔, 위치 등 기준을 나타내는 문서

와이어프레임 예시

• 구동 환경
  • 해당 소프트웨어가 구동되기 위한 물리적, 논리적 조건을 설명합니다.
• 요구 성능
  • 해당 소프트웨어가 원할하게 처리해야하는 목표 요구치를 의미합니다.
    • 어떤 예시가 있을까요?
      • ‘최대 10만명의 동시 접속자를 처리할 수 있어야한다.’
      • ‘결과값은 최대 15초를 넘기지 않고 결과값을 도출해야한다.’
      • ‘비교군 10,000개에 대해 예측률이 최소 95% 이상이여야한다.’
      • ‘최대 2페타바이트의 데이터를 수용 및 처리할 수 있어야한다.’
• 제한 사항
  • 해당 소프트웨어가 원할하게 사용되기 위한 제한 사항을 의미합니다. 이 사항에 대해서는 기술진들이 이해관계자들에게 제한 사항에 대해 충분히 납득할 수 있도록 설득해야하는 상황이 올 수도 있습니다.
    • 어떤 예시가 있을까요?
      • ‘해당 기기는 80°C 이하에서 작동해야한다.’
      • ‘방수 터치 패드는 표면으로부터 수심 1m까지만 사용해야한다.’
      • ‘쵀대 접속량은 8만명으로 제한한다.’
      • ‘인터넷익스플로 브라우저를 통한 접속에 대해서는 지원하지 않는다.’

---

SDS (Software Design Standards, 소프트웨어 설계 사양서)

소프트웨어의 전반적인 설계에 대해 상세하게 명세한 문서

• 작성에 필요한 조치들
  • 소프트웨어를 설계하기에 가장 적합한 핵심 기술진의 주도하에 SRS문서에 맞추어 SDS문서를 작성하도록합니다.
  • 최소 비용과 최대 효율을 적절하게 계산하여 설계합니다.
  • 목표 개발 일정을 고려하여 절차에 따라 설계합니다.
  • 반드시 유지보수성을 고려하여 설계합니다.
  • 기술진이 주도 하에 작성합니다.
• SDS에 담겨야하는 내용 예시
  • 와이어프레임
    • UX를 고려하여 만든 UI로 각 인터페이스가 어떤 역할을 하는지, 대략적인 모양, 색깔, 위치 등 기준을 나타내는 문서

와이어프레임 예시

• 단, 여기서는 최대한 개발자의 의도보다 SRS문서에 따른 와이어프레임의 내용을 적용합니다.
• 개발 환경
  • 해당 소프트웨어를 개발하기위한 물리적/논리적 환경을 의미합니다.
    • 어떤 예시가 있을까요?
      • 프로그래밍 언어는 python 3.10.8을 적용한다.
      • IDE는 vscode 또는 pycharm을 사용한다.
      • SQL은 SQLite 3.46을 적용한다.
• 디자인 패턴
  • 어떤 구조로 구현할것인지 정의합니다.
    • MTV 패턴을 적용한다. (SDS는 기술진을 위한 문서이기에 자세한 설명을 작성하지 않아도 될 것같지만 반드시 각 명칭에 대해 옳바른 정의 및 설명을 거의 전부 써주어야합니다.)
• 연계 기술
  • 함께 연계되는 기술들은 어떤것들이 있는지 작성합니다.
    • Tensorflow 2.0
    • ChatGPT-4
    • 주요 기술들과 함께 개발 언어와 SQL에 대한 내용도 함께 포함하여 작성합니다.
    • 버전까지 꼭 명시해주기!
• 구동 환경
  • 본 소프트웨어가 구동되기 위한 환경에 대해 설명합니다.
    • Windows 8~10
    • IOS 15.1~17.5
• API 명세서
  • 사용되는 메소드에 대한 이름, 기능, url, end-point, 목적, 필요 매개변수 등 모든 사항을 표 형태로 기재합니다.

API 명세서

• UML (Unified Modeling Language, 통합 모델링 언어)
  • 그림과 관계도를 그려서 누구나 쉽게 알아볼 수 있도록 하는 다이어그램입니다.
    • 클래스 다이어그램
      • 클래스간 어떤 관계를 나타내고 있는지, 어떤 객체를 왜 어떻게 사용하는지 표현하는 다이어그램을 의미합니다.

Class 다이어그램 예시

• ERD(Entity Relationship Diagram, 개체 관계 다이어그램)
  • DB에서 각 개체 간에 어떤 관계를 나타내는지 표현한 다이어그램

ERD 예시 (* 원래는 다 영어로 작성해야함 주의!)

• 파일 구조
  • 소프트웨어의 전반적인 파일 구조를 설명합니다.
    • 반드시 각 폴더 및 파일이 어떤 역할을 하는지 설명해야합니다.
    • 예시

├── static/
│   ├── css/
│   ├── js/
│   ├── images/
│   └── ...
├── media/
│   ├── profile_pictures/
│   ├── documents/
│   └── ...

---

SCS (Software Code Standards, 소프트웨어 코드 사양서)

소프트웨어를 개발하기 위한 작성할 코드에 대한 표준 문서를 의미해요.

• 작성에 필요한 조치들
  • 철저하게 소프트웨어 개발진을 위한 문서가 되어야합니다.
  • 유지보수를 고려하며 작성합니다.
  • 인수인계를 고려하며 작성합니다.
  • 국제 표준을 준수하도록 작성합니다.
  • 최대한 간단하지만 명료하게 작성합니다.
• SCS에 담겨야하는 내용 예시
  • 개발 환경, 프로그래밍 언어
  • 개발 방식
    • 보통 디자인 패턴과 파일 구조 등 개발 하기 위한 공통된 방식을 정의합니다.
  • 코드 컨벤션
    • 소스코드를 작성할 때 공통된 방식으로 작성하도록 정의합니다.
  • 이슈 처리 방법
    • 프로그램적인 문제가 발생하였을 때 어떻게 대응하는지에 대해 정의합니다.
  • 형상 관리에 관한 전반적인 내용
    • 형상 관리 주기, commit 컨벤션 등 전반적인 내용을 정의합니다.

---

WBS (Work Breakdown Structure, 업무 분류 체계)

프로젝트를 수행하기 위한 업무를 분류하여 정리한 문서

• 작성에 필요한 조치들
  • 개발 목표 일정과 기한을 넘지 않도록 계획합니다.
  • 개발 담당자를 통해 적절한 개발 기간을 확보합니다.
  • 적절한 업무의 분배가 이뤄지도록 작성합니다.
• WBS에 담겨야하는 내용 예시
  • 개발 일정
  • 개발 항목
    • 개발 항목은 기능단위로 대분류, 중분류, 소분류로 나누어 세분화합니다.
      • 예시
      • 대분류는 가장 큰 단위로 back-end, front-end 이런식으로 나눌 수 있고
      • 중뷴류는 중간 단위로 back-end에서 DB, API, 이런식으로 나눌 수 있고
      • 소분류는 가장 작은 단위로 최소 기능단위의 함수나 클래스, 또는 튜터 말 잘듣기 기능, 수강생 숙제시키기 기능 등 정말 최소단위의 기능을 의마합니다.
  • KPI (핵심 성과 지표)
    • 본래 KPI를 별도의 부서에서 별도의 문서로 작성 및 관리하기도 하지만 개발 일정에 맞춰서 KPI를 함께 내포하여 작성하기도 합니다.

---

Verification & Validation (검증 및 확인)

소프트웨어의 신뢰성과 성능을 보장하기 위해 작성하는 문서들의 모음 (하위에 있는 항목들은 프로젝트의 규모가 커질 수록 별도로 문서화가됩니다.)

 

Verification & Validation에 담겨야하는 내용

• TestPlan: 시험 계획
• TestCase: 시험 항목
• 사이버보안 check list: 사이버보안에 관련된 검증 및 확인 항목들
• 제한사항: 검증 및 확인을 하기 위한 제한 사항을 의미합니다.
  • 예를 들어서 최대 동시 20만명에 대한 트래픽까지 시험을 진행해야하는데 100만명을 시험한다던지 그런 불필요한 일들을 방지하기 위한 항목입니다.
• UX 관련된 피드백 보고서
  • 구현된 UI을 사용하며 사용자 경험에 대한 보고서들을 의미합니다.

---

그외 여러가지 문서들

사용자 설명서(User Manual)

• 사용자를 위한 소프트웨어 안내서/지침서/설명서를 의미합니다.
• 주로 어떻게 사용하는지에 대한 내용이 담겨있습니다.

관리자 안내서(Administrator Guide)

• 관리자를 위한 솦트웨어 안내서/지침서/설명서를 의미합니다.
• 주로 관리자가 해당 소프트웨어를 어떻게 제어하고 어느 권한까지 가능한지에 대한 내용이 담겨있습니다.

라이선스에 관한 문서

• 해당 소프트웨어에 대한 저작권을 표시합니다.

---

현업에서 문서 작성 능력은 정말 생각보다 많이 필요해요. R&D 분야라거나 거대한 프로젝트를 진행한다면 더더욱! 

여기에 있는 문서들 외에도 정말 여러가지 문서들이있어요. 회사마다, 산업마다, 부서마다, 프로젝트마다 작성해야하는 문서들이 달라집니다. 위에 있는 모든 문서를 작성해야하는 것도 아니고 필요에 따라 적절하게 작성하면됩니다.