개발자인가 서기인가, 소프트웨어 문서 작성하기

개발자인가 서기인가 

 

할 정도로 많은 문서를 작성하게 되는게 개발자라고 한다. 문서를 작성하는 이유는 예전 민준튜터님 특강에서 배웠듯이, 소프트웨어의 구조를 '설계'하고 표준을 지향하는 '소통'을 하기 위해서다. 암튼 말 잘 하는 사람이 영업을 잘 하는 것처럼 문서작성을 잘해야 취업도 되고 투자도 받고 상사한테도 인정받을 수 있다는 것.

 

그럼 어떻게 문서화 해야할까?

 

1. 읽기 쉬운 문서를 작성한다.

읽는 사람 관점에서 쉬운 문서를 작성해야 한다. 문서에 따라 다르겠지만 만약 투자자가 보는 문서에 불필요한 내부 전문용어들이 있다면 문서를 읽고 빠르게 이해하는데 장애물이 될 뿐이다.  그리고 작성자가 문서를 조급하게 쓴다면 머릿속에 떠오른 순서대로 문서를 작성하게 된다. 이건 독자를 위한 구조가 아니다. 보통은 소프트웨어의 실행 흐름에 따라 작성했을 때 읽기가 수월하다.

 

2. 불필요한 반복을 피한다.

정보는 종류별로 반드시 한군데에만 기록해야 한다. 그래야 문서를 활용하기 편하고 무엇보다 유지보수에 드는 노력이 줄어든다. 정보를 확인하는데 반복된 정보가 있고 심지어 두 정보가 상이하다면 읽는 사람은 패닉에 빠지게 된다.🤔

 

3. 모호함을 피한다.

소프트웨어 문서를 읽었을 때, 여러 의도로 해석될 수 있다면 문서가 잘못된 것이다. 예를 들어 동그라미가 네모를 가리키고 있는데 가리키는 선이 삼각형으로 되어 있다면 과연 그 선은 삼각형일까 선일까? 상속을 뜻하는걸까 동기화를 뜻하는 걸까? 알기가 어렵다. 그러므로, 가능한 한 독자가 표기법의 의미를 파악하기 쉽도록 기호에 대한 범례를 표시하여 한가지 뜻으로만 이해할 수 있도록 해야한다. 

 

4. 표준체계 문서양식을 따른다.

표준 문서 체계를 정하고, 그 체계에 따라 독자들이 문서를 읽도록 유도해야 한다. 표준을 따르면 독자는 특정정보를 빠르고 정확하게 찾을 수 있다. 또한 정보의 완결성 규칙도 준수할 수 있기 때문에, 문서를 적는사람 입장에서도 한결 수월하다.

 

5. 근거를 남긴다.

의사 결정의 결과를 문서화 할 때는 결과 뿐만 아니라 결과를 선택하는 과정에 대해서도 명확히 기록하는게 좋다. 

 

6. 최신 내용을 담되 앞서나가지 않는다.

항상 최신 내용을 적용해야한다. 하지만 소프트웨어를 설계하는 과정을 거치다 보면 의사결정 과정에서 다시 생각해보거나 수정하는 일이 빈번하다. 곧 뒤집힐 결정을 반영하여 문서에 적는 건 낭비다.

 

7. SDLC(소프트웨어 개발 수명 주기)를 생각하며 작성한다.

개발 과정의 명확성을 높일 수 있다. 명확한 문서는 팀 간 효율적인 커뮤니케이션과 문제 해결을 지원하기 때문에 궁극적으로 프로젝트를 성공적으로 이끌어가는데 큰 역할을 한다.

 

8. 목적에 맞게 작성됐는지 검토한다.

문서에 담고자 했던 정보가 정상적으로 들어갔는지 확인하고, 실제 독자에게도 문서를 보여줘서 양식을 준수하고 있는지 확인 해야한다.

 

 

문서 작성은 귀찮은 일처럼 느껴지기도 하지만 내 프로젝트의 얼굴이므로 정확하게 잘 알고, 잘 써야 한다. 하나의 소프트웨어를 함께 설계하고 개발하고 사용하듯이, 누구에게나 쉽고 명확하게 읽을 수 있는 문서를 적는 것도 함께 가져가야 하는 당연하고도 올바른 업무인 것 같다.

 

 

아래는 소프트웨어 문서의 종류들이다.

 

---

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

 

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

 

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

 

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

---

SDS (Software Design 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)
  • 관리자를 위한 솦트웨어 안내서/지침서/설명서를 의미합니다.
  • 주로 관리자가 해당 소프트웨어를 어떻게 제어하고 어느 권한까지 가능한지에 대한 내용이 담겨있습니다.
• 라이선스에 관한 문서
  • 해당 소프트웨어에 대한 저작권을 표시합니다.

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

•