2022 State of DevOps Report data deep dive: Documentation is like sunshine 문서에 대한 번역입니다. 한국어 블로그에 번역이 올라오긴 하지만 약 한 달 정도 차이가 있는 것 같더군요. 개인적인 학습 용도이며, 아마도 이 글을 보는 것보다 이 글을 작성한 시점보다 좀 더 나아진 기계번역의 힘을 빌리는 것이 좀 더 좋은 방법이라 생각됩니다.
June 16, 2023
https://cloud.google.com/blog/products/devops-sre/deep-dive-into-2022-state-of-devops-report-on-documentation?hl=en
기술 조직의 내부 문서는 소프트웨어 개발의 기본적인 부분입니다. 지난 2년 동안 DORA 팀은 내부 문서의 품질을 조사했습니다. 이를 통해 문서 품질과 조직의 성과(수익 목표를 달성할 수 있는 능력) 사이에 분명한 연관성이 있다는 것을 발견했습니다. 식물이 잘 자라려면 물과 햇살이 필요하듯이, 좋은 기술 관행과 문서화를 갖춘 조직은 조직의 목표를 달성하거나 초과 달성할 가능성이 훨씬 더 높습니다.
문서화는 고도로 기술적인 작업이며, 이번 조사 결과는 이런 작업이 얼마나 큰 성과를 거두는지 보여줍니다. 이번 글에서는 다음과 같은 내용을 다룹니다.
- 문서 품질을 정의하고 측정하는 방법
- 문서화가 기술 역량과 조직 성과에 미치는 영향
- 문서 품질을 높이기 위해 팀에서 실행할 수 있는 방법
문서 품질은 어떻게 측정하나요?
문서 품질과 관련된 루멘이나 와트 같은 단위가 없기 때문에 문서 품질을 정의하고 측정하는 방법을 고안해야 했습니다.
연구를 위해 명확성, 검색 가능성, 신뢰성과 같은 문서 속성을 평가하는 8가지 지표를 사용했습니다. 이런 속성을 평가하는 데 사용한 문항은 2022년 설문조사에서 확인할 수 있습니다.
https://dora.dev/research/archives/2022/
각 응답자에 대한 응답을 집계한 다음 0에서 1 사이의 숫자로 표현해 표준화된 점수를 부여했습니다. 각 점수는 우리가 가지고 있는 모델에 추가해 나머지 시스템과 어떻게 상호 작용하는지 알아냈습니다.
문서화는 봄날의 햇살입니다.
2021년 연구와 마찬가지로 문서 품질이 기술 관행의 구현을 주도하는 것으로 나타났습니다. 2022년 모델은 문서화가 이런 기술 역량을 뒷받침하는 것을 보여줍니다.
그러나 더 흥미로운 것은 문서 품질이 이런 역량과 상호 작용하면서 조직 성과에 영향을 미치는 방식입니다.
다음 그래프에서는 지속적 통합과 문서 품질이 어떻게 상호 작용하며 조직 성과에 영향을 미치는지 시각화해서 보여줍니다.
그래프는 데이터를 기반으로 한 세 가지 시뮬레이션 예측 세트를 살펴봅니다. 각 세트에는 데이터에 존재하는 불확실성(또는 확실성)의 정도를 파악하는 데 도움이 되는 4000여 개의 시뮬레이션된 예측이 있습니다.
- 녹색으로 표시된 맨 위 집합은 문서 품질이 평균 이상(평균보다 1 표준편차 높음)입니다.
- 노란색으로 표시된 중간 집합은 문서 품질이 평균 수준입니다.
- 빨간색으로 표시된 집합은 문서 품질이 평균 이사(평균보다 1 표준편차 낮음)입니다.
X축에는 지속적인 통합 관행의 구현이 있습니다. 이런 기술적 관행이 구현되면 조직의 성과에 긍정적인 영향을 미칩니다. 이런 영향은 문서의 품질이 높아질수록 증폭됩니다.
햇살과 물이 있으면 식물은 잘 자라고 번성합니다. 양질의 문서가 있으면 기술 관행은 수익에서 고객 만족에 이르기까지 조직의 성과를 높이는 데 도움이 됩니다.
이런 상호 작용과 영향은 2022년에 연구한 모든 기술 역량에 적용됩니다. 아래 표에서 다양한 기술 역량을 구현할 때 조직 성과가 얼마나 향상되는지 확인해 보세요. 문서 품질이 평균 이상인 팀의 경우 성과가 크게 증폭됩니다.
| 조직 성과 향상 | ||
| 기술 역량 | 문서 품질이 평균 이하인 팀 | 문서 품질이 평균 이상인 팀 |
| 지속적인 배포 | 63% | 656% |
| 지속적인 통합 | 34% | 750% |
| 느슨한 결합 아키텍처 | 46% | 313% |
| 사이트 신뢰성 엔지니어링(SRE) | 79% | 343% |
| 공급망 보안 | 37% | 451% |
| 트렁크 기반 개발 | 36% | 1525% |
| 버전 관리 | 27% | 278% |
문서화가 어떤 영향을 미치나요?
여러 가지 추측이 있을 수 있습니다. 예를 들면, 글쓰기 행위는 변화를 이끌어내는 특성이 있어 문서를 작성하면 작업의 기술적 품질이 향상된다는 주장이 있습니다.
2019년 데브옵스 현황 보고서를 비롯해 여러 연구에 따르면 생산성과 문서와 같은 내부 지식 소스에 대한 접근 사이에 연관성이 있는 것으로 나타났습니다. 기술 관행을 성공적으로 구현하고 있지만 문서 품질이 좋지 않은 팀은 많은 노력을 기울이더라도 전반적인 생산성이 떨어질 수 있습니다.
어쩌면 우리가 보고 있는 것은 품질이 낮은 문서로 작업하면서 기능을 구현한 팀이 이런 성공에서 고립되어 있다는 것입니다. 그들은 어려움을 겪고 있는 다른 팀에 둘러싸여 있을 수 있습니다. 반대로 양질의 문서가 있는 상태에서 기술적 성공을 거두면 조직 구성원이 바뀌거나 시간이 지나더라도 비슷한 수준의 기술적 성공을 거둘 수 있습니다.
이런 모든 요인과 다른 요인이 복합적으로 작용해 문서화의 효과가 크게 나타나는 것일 수 있습니다. 확실한 것은 문서 품질이 기술 관행의 성공적인 구현에 상당한 영향을 미친다는 것입니다. 그리고 양질의 문서는 이런 기술 관행이 조직 성과에 미치는 긍정적인 영향을 크게 증폭시킵니다.
양질의 문서를 작성하려면 어떻게 해야 할까요?
모든 식물이 자라기 위해서는 햇살이 필요하지만 다행히도 태양은 항상 하늘 위에 있습니다. 문서는 햇살과 비슷하지만 태양과 같지는 않습니다. 문서는 적극적으로 작성하고 유지 관리해야 하며, 이를 위해서는 노력이 필요합니다.
2021년 데브옵스 현황 보고서에서 문서 품질을 개선하기 위해 구현할 수 있는 사례에 대한 지침을 확인할 수 있습니다.
https://cloud.google.com/resources/state-of-devops?hl=ko
이번 연구에서 개별 리소스를 조사하지는 않았지만 유용한 문서를 작성하는 데 도움이 되는 많은 자료가 있습니다. 여러분의 조직에 문서화 가이드라인과 문서 작성 교육이 있을 수 있습니다. 또한 테크니컬 라이터나 기타 문서화 담당자의 도움을 받을 수 있습니다. 구글에서 제공하는 문서화 리소스는 다음과 같습니다.
- 소프트웨어 엔지니어를 위한 기술 문서 작성 과정 https://developers.google.com/tech-writing
- 구글 개발자 문서 스타일 가이드 https://developers.google.com/style
- 구글에서는 이렇게 일한다의 문서화 챕터 https://hanbit.co.kr/media/books/book_view.html?p_code=B1207366943
운 좋게도 양질의 문서가 많은 환경에서 일할 수 있다면 그것은 여러분이나 조직의 사람들이 그런 콘텐츠를 만들기 때문일 것입니다. 하지만 조직의 문서 품질이 좋지 않다면 여러분이 햇살이 되어보세요. 위에 소개한 관행을 구현함으로써 문서 품질을 개선하고 봄날의 햇살을 만날 수 있습니다.
