문서 중심 개발에 대해 무엇을 알고 있습니까?

개발 과정에서 왜 문서가 필요한가요?

코드 자체를 문서화 하는 이 진술은 어떻습니까?

가장 일반적인 시나리오를 생각해 봅시다. 시스템의 코드(프로그램, 프로젝트 또는 제품)가 장기간에 걸쳐 작성되고 팀은 이 프로세스 동안 점진적으로 변경되어 개발자가 떠날 때 시스템에 대한 특정 지식을 가져옵니다.

그러한 경우에 우리는 무엇을 할 수 있습니까?

가장 간단한 대답은 시스템이 원래 요구 사항을 충족하는지 확인하기 위해 모든 구현 세부 사항을 캡처하는 사양을 작성하는 것입니다.

그러나 이러한 문서는 미리 작성하기가 매우 어려우며, 개발 과정에서 일부 구현 세부 사항이 변경될 수 있습니다(시장 적응/메커니즘에 대한 새로운 요청 등). 그렇다면 버스 팩터를 개선하기 위해 우리는 무엇을 고안할 수 있을까요?

위에서 언급한 문제를 해결하기 위한 가능한 해결책 중 하나가 될 수 있는 흐름을 따라가 보겠습니다.

요구 사항 및 RFC

먼저, 이해관계자의 요구사항을 기반으로 초기 설계를 설명하고 문서화해야 합니다. 그 후, 이 문서는 다른 팀과 공유될 수 있으며 특정 기능 구현 요청, 초기 디자인에 대한 의견 제시, 특정 인터페이스 수정 등의 피드백을 요청할 수 있습니다. 이러한 문서를 RFC 라고 부를 수 있습니다.

RFC 또는 "의견 요청"은 피드백, 의견 및 제안을 수집하기 위해 개발자, 설계자 및 기타 팀을 포함한 이해 당사자 간에 배포되는 문서입니다. 이는 사양보다 덜 상세하며 초기 문제, 작업 및 솔루션 영역만 포함합니다. 더욱 유연해지기 때문에 설계 변경을 적극적으로 수용할 수 있어 작업에 대한 깊은 이해를 보장하고 품질과 사려 깊은 의사 결정을 촉진할 수 있습니다.

설계 약속 및 ADR

자, 우리는 기술적 요구 사항을 정의 하고 다른 팀의 요구 사항을 수집했습니다 . 무엇 향후 계획?

이 단계에서는 시스템 설계와 시스템이 수행할 모든 주요 기능을 마무리 해야 합니다. 이를 위해 우리는 ADR을 작성합니다.

ADR , 즉 "아키텍처 결정 기록"은 소프트웨어 개발 프로세스 중에 내려진 중요한 아키텍처 결정을 기록하는 문서입니다. 각 ADR은 특정한 상위 수준 아키텍처 결정, 해당 컨텍스트, 고려된 대안, 결정 및 다른 세부 사항보다 이러한 특정 세부 사항을 선택하는 동기를 설명합니다.

이러한 문서를 통해 모든 팀 구성원(및 다른 팀)은 디자인을 뒷받침하는 원칙과 가치를 이해할 수 있습니다 . 몇 년 후 새로운 개발자가 팀에 합류하여 "왜 이런 식으로 했나요?"라고 묻는 경우 모든 질문에 답할 수 있는 이 문서를 볼 수 있습니다.

사양

이제 코드와 사양을 작성할 차례입니다. 이 단계에서 우리는 각 기능을 철저하게 작업하는 동시에 모든 정보와 구현 세부 사항을 특수 문서로 컴파일합니다. 이 문서는 시스템에 대한 현재의 낮은 수준 요구 사항을 반영해야 합니다.

중요한 점 은 소프트웨어 수명주기 동안 이러한 사양이 크게 변경될 수 있다는 것입니다. 그러나 코드베이스가 관리하기 어려운 상태가 되는 것을 방지하려면 원래 디자인과 아키텍처를 유지하는 것이 매우 중요합니다.

테스트 계획

왜 필요한가요? 사양에 따라 작성된 코드(우리는 이 코드에 대해 코드를 작성하고 테스트하여 통과하도록 함)를 기반으로 테스트 계획을 수립하는 것이 아니라 다음과 같은 중요한 시나리오를 포함하는 설계를 기반으로 테스트 계획을 수립하는 것이 중요합니다. 올바르게 처리되어야 합니다 . 또한 검토를 위해 이러한 테스트 계획을 다른 팀(통합 또는 추가 테스트용)에 제출하여 시스템이 다양한 상황에서 어떻게 작동할지 명확하게 할 수 있다는 점도 매우 편리합니다.

그것은 무엇을 포함합니까?

• 가능한 모든 시스템 작동 시나리오

  • 행복한 길
  • 슬픈 길
  • 오류 처리

• 시스템 작동 중에 유지되어야 하는 모든 가능한 불변성

• 초기에 시스템 상태를 확인하기 위한 승인 테스트(네트워크의 데이터 등 환경을 고려해야 함)

  
  

우리는 디자인을 마무리하고, 코드와 사양을 작성하고, 테스트 계획을 작성했습니다. 이미 꽤 견고한 것 같습니다! 하지만 또 무엇을 추가할 수 있을까요?

배포 계획

이러한 계획은 버스 요소를 개선 하고 모든 팀 구성원이 시스템을 배포하고 상태를 확인할 수 있는 조건을 만들기 위해 어느 정도 필요할 수 있습니다.

그것 없이는 왜 할 수 없습니까? 가능하지만 실제로는 많은 사람이 시스템의 다양한 부분을 담당하고 배포 프로세스가 DevOps에 완전히 위임되는 대규모 팀이 있을 수 있습니다. 테스트를 작성하고 이를 CI에 넣고 취약점을 확인했으니 다른 것이 더 필요한가요? 아닐 수도 있지만 테스트에서는 시스템의 현재 상태를 고려하지 않고 우리가 원하는 대로 테스트하지 않는 경우가 많습니다.

배포 계획에는 다음이 포함될 수 있습니다 .

• 배포를 수행하기 위해 수행해야 하는 작업에 대한 전체 설명
• 배포 매개변수:
  • 환경 변수
  • 초기 상태
  • 실행 매개변수
• 어떤 단계에서든 문제가 발생할 경우를 대비한 계획
• 가능한 경우 백업 계획
• 배포를 계속할 수 없는 경우 시스템을 가져와야 하는 필수 상태입니다.
• 배포 후 수행해야 할 작업
  • 다른 팀에 알림
  • 필요한 경우 필요한 통합을 활성화합니다.

복잡한 건 하나도 없지, 그렇지? 특정 업데이트에 대한 이러한 문서가 있으면 버스 요소가 크게 향상 되고 특정 개인에 대한 의존을 방지 할 수 있습니다. 그것이 우리가 원하는 것이 아닌가?

결론

소프트웨어 개발 프로세스에서는 코드를 작성하는 것뿐만 아니라 모든 개발 단계에서 이해와 일관성을 보장하는 문서를 작성하는 것도 중요합니다. 문서화는 코드 그 자체일 수 있지만 , 경험에 따르면 문서화는 시스템의 품질, 안정성 및 향후 확장성을 유지하는 데 매우 중요하며, 특히 개발 중에 팀이 변경될 때, 그리고 프로젝트가 발전하고 새로운 요구 사항에 적응할 때 더욱 그렇습니다.

문서에는 RFC (의견 요청), ADR (아키텍처 기록), 사양 , 테스트 계획 , 배포 계획 등이 포함됩니다. 이를 통해 팀 내 지식 유지가 보장되고, 신규 직원을 프로젝트에 통합하는 프로세스가 단순화되며, 시스템의 전반적인 신뢰성과 변화에 대한 저항력이 향상됩니다 .