개발시, 반드시 작업을 문서화하는 습관 들이기!

요건 정의서, 개발 보고서, 테스트 완료서 등과 같은 문서화는 소프트웨어 개발 프로세스에서 매우 중요한 역할을 수행한다.

필자도 처음에는 개발시, 문서화의 중요성을 망각하고 가이드라인 없이 무작정 개발을 진행했던 적이 있다. 물론 작은 프로젝트같은 경우에는 문서화 작업 없이도 별 문제 없이 진행했었다.

 

그러나 다루는 프로젝트의 규모가 점점 커지고, 여러 개발을 진행하게 되면서,문서화의 필요성을 마주하게 되었다.

내가 무엇을 개발할 것이며, 내가 무엇을 개발하고 있으며, 어떤 문제에 맞닥뜨렸고, 이를 어떻게 해결했고, 개발 완료가 어떻게 됐는지에 대한 기록이 없다면, 나중에 시간이 흐른 후 다시 들여다봤을 때, 생전 처음 보는 코드를 맞닥뜨릴 수도 있다. 

물론 익숙해지기 전까진, 개발자에게 문서화란 무척 귀찮고 지루한 작업일 수도 있다. 당장은 문서화하는 게 프로젝트 시간을 훬씬 증가시킬 뿐더러, 이걸 굳이 써야돼? 라는 생각들이 들 것이다.

그러나 개발자또한 결국 혼자서 일을 하는 것이 아닌, 누군가와 협업을 해야 할 일들이 아주 많고, 특히 필드에 나간다면, 진행중이던 프로젝트에 중간 합류를 할 수도 있고, 누군가에게 내가 개발중인 것을 presentation해야 할 상황이 분명 있을 것이다. 그럴 때, 체계적인 문서화가 되어 있는 프로젝트가 반드시 빛을 발하게 될 것이다.

 

그렇기 때문에, 자신만의 문서화하는 틀을 입맛대로 만들어보고 이를 습관화하는 것은 매우 중요하다.

 

 

다음은 이러한 문서화의 중요성에 대한 몇 가지 이유를 소개해보려 한다. 

 

1.  의사 소통 개선: 요건 정의서는 프로젝트의 목표와 기대되는 결과물을 명확하게 정의하여 팀 간 의사 소통을 개선합니다. 개발 보고서와 테스트 완료서는 개발 진행 상황과 테스트 결과를 효과적으로 전달하여 팀원들이 프로젝트 상태를 파악하고 필요한 대응을 취할 수 있도록 도와줍니다.
2. 기능 및 요구사항 파악: 요건 정의서는 프로젝트의 기능과 요구사항을 명세화하여 모든 팀원이 공통된 이해를 갖게 합니다. 이를 통해 개발자들은 어떤 작업을 수행해야 하는지, 기능들이 어떻게 상호작용해야 하는지를 파악할 수 있습니다.
3. 변경 관리: 요건 정의서와 개발 보고서는 변경 사항을 추적하고 관리하는 데 도움을 줍니다. 프로젝트 진행 중에 요구사항이 변경될 수 있으며, 이러한 변경 사항을 문서화하여 추적함으로써 프로젝트의 안정성과 일관성을 유지할 수 있습니다.
4. 품질 보증 및 테스트: 테스트 완료서는 프로젝트의 품질을 보증하는 데에 중요한 역할을 합니다. 테스트 완료서를 통해 모든 테스트 케이스와 결과를 문서화하고, 발견된 결함들을 추적하여 해결할 수 있습니다. 이는 소프트웨어 제품의 신뢰성과 안정성을 향상시키는 데 도움이 됩니다.
5. 지식 공유와 교육: 문서화를 통해 프로젝트의 지식과 노하우를 기록하고 공유할 수 있습니다. 새로운 팀원들이나 다른 프로젝트에서 개발자들은 문서를 활용하여 프로젝트 이력과 학습 자료를 얻을 수 있습니다.
6. 프로젝트 관리와 계획: 요건 정의서와 개발 보고서는 프로젝트 관리와 계획에 도움을 줍니다. 프로젝트 진행 상태를 파악하고 리스크를 평가하는 데에 활용할 수 있으며, 프로젝트의 마일스톤과 일정을 설정하는 데에도 도움이 됩니다.
7. 법적 및 규정 준수: 일부 산업이나 규제 기관은 문서화를 필수로 요구합니다. 요건 정의서와 개발 보고서, 테스트 완료서 등은 이러한 법적 요구사항과 규제를 준수하는 데에 필요합니다.

 

다음은 문서화하는 과정이다.

참고로 필자는 문서를 총 3단계로 분류하는데, 개발전 문서화/ 개발중 문서화 / 개발후 문서화 이렇게 세 단계이다.

자세한 단계 및 설명은 아래와 같다.

 

1. 개발 전 문서화

- 요건 정의서 작성

   : 프로젝트의 목표와 기대되는 결과물을 정의하는 문서를 작성합니다. 이 문서는 프로젝트의 범위를 파악하고 목표를 이해하는 데에 도움이 됩니다.

- 설계서 작성

   : 소프트웨어의 아키텍처, 모듈 구조, 데이터 흐름 등을 설계하는 문서를 작성합니다. 이 문서는 개발자들이 구현 전에 전체적인 시스템 구조를 이해하는 데에 도움이 됩니다.

2. 개발 중 문서화

- 개발 보고서 작성

   : 개발 중에는 주기적으로 개발 진행 상황과 이슈를 기록하는 개발 보고서를 작성합니다. 이 보고서는 프로젝트 관리와 의사 소통에 중요한 역할을 합니다.

- 주석 및 문서화 코드 (문서화를 따로 안 하는 사람도 개발자라면.."주석"쯤은 달아 봤을 것이다...)

   : 개발 중에 코드에 주석을 추가하고, 함수와 클래스 등을 설명하는 문서화를 수행합니다. 이렇게 함으로써 다른 개발자들이 코드를 이해하고 유지보수하기 쉬워집니다.

3. 개발 후 문서화:

- 테스트 완료서 작성

   : 테스트 과정에서 수행한 테스트 케이스, 결과, 발견된 결함들 등을 문서화하여 테스트 완료서를 작성합니다. 이 문서는 소프트웨어의 품질 보증과 결함 관리에 사용됩니다.

- 사용자 매뉴얼 작성

   : 최종 사용자가 소프트웨어를 사용하는 데에 도움이 되는 사용자 매뉴얼을 작성합니다. 사용법, 기능 설명, 문제 해결 방법 등이 포함될 수 있습니다.

- 유지보수 문서화

   : 소프트웨어의 유지보수를 위해 변경 사항을 문서화하고, 코드를 업데이트한 내용과 이유를 기록합니다.

 

이 때, 양식은 자유롭다!

필자는 보통 워드 / 엑셀을 사용하거나, Notion을 사용해 한 번에 작성하기도 한다.

 

지금부터는 실제로 필자가 작성했던 문서들을 몇 개 첨부하려 한다.

 

 

- 개발 기능 요건정의서

-> 다음 문서는 요건정의서에서 설계서의 기능도 일부 할 수 있는 자세한 요건정의서라고 볼 수 있다.

워드로 작성하였고, 형식은 따로 나와있는 걸 사용하진 않았고, 필요에 따라 직접 구성하였다.

 

- 개발 보고서

-> 개발 보고서이다. 개발한 부분, 주요 코드 설명 등을 작성하였다.

이것도 역시 따로 나와있는 형식은 아니고, 필요한 항목들을 직접 추가해 구성했다.

 

 

- Test 보고서

-> 테스트 보고서이다. 개발이 끝난 뒤, 해당 프로젝트를 테스트하고 이 결과를 기록한 것이다.

 

 

이런 식으로 개발 작업을 문서화하면, 당시에는 조금 귀찮아도, 시간이 흐를 수록 더 가치가 높아지는 것 같다.

필자도 처음엔 문서화를 극도로.. 싫어했지만.. 이제는 오히려 얼마나 더 잘 설계하고 기록했느냐가 프로젝트의 완성도를 결정지을 수도 있겠다는 생각을 하기도 했고,

프로젝트가 옳은 방향으로 개발되고 있는 지도 바로바로 확인할 수 있다는 장점이 있다는 생각을 하게 되었다.

 

ps... 나름 꼼꼼한 성격과 기록하기를 좋아하는 성격 덕에 문서화를 체화하기가 비교적 쉬웠던 것 같다...!