"2022 데브옵스 현황 보고서 데이터 심층 분석: 문서화는 봄날의 햇살입니다"와 관련된 세션입니다.
https://koko8829.tistory.com/2413
연구 결과에 대해 간단하게 설명하는 자리였구요. 일단 해당 문서는 외부에 공개되는 기술 문서가 아니라 조직 내부에서 사용하는 기술 문서에 대한 연구였다고 합니다(좀 설명이 애매하긴 한데). 엔지니어들이 자신의 팀에서 관리하는 기술 문서가 개발 프로세스에 어떻게 영향을 주는지 확인하는 작업이었다고 합니다.
2023년 보고서까지 공개가 되어있구요. 2024년 서베이가 진행되고 있습니다. 주로 북미 쪽에서 나온 답변을 위주로 작성된 보고서이기 때문에 문화적인 차이에 따라 다를 수 있습니다.
문서 품질과 관련된 8개 속성과 관련된 질문이라고 합니다. 23년 설문에서는 질문이 좀 줄어든 것 같구요. 이 지표가 어떤 기준으로 작성되었냐는 질문이 Q&A에서 나오긴 했는데 여러 문서를 참고했다 정도만 답변했습니다.
- Reliable (functional)
I can rely on our technical documentation when I need to use or work with the services or applications I work on
- Clear
It is easy for me to understand our technical documentation
- Findable
It is easy to find the right technical document when I need to
- Comprehensive
Most of the code for the services or applications I work with is documented
- Organized
Our technical documentation is well organized
- Up-to-date
Technical documentation is updated as changes are made
- Accurate
The technical documentation correctly reflects the capabilities and requirements of the primary service or application I work on
- Relevant
When there's an incident or problem that needs troubleshooting, I reach for the documentation
Q&A
문서 품질이 직접적인 조직 성장의 요인이라고 이야기할 수는 없지만 서로 영향을 미친다는 것은 알 수 있습니다. 이걸 어떤 것이 먼저냐라고 물어보는 것은 닭과 계란처럼 정답을 이야기하기 어렵습니다.
문서화를 개선하기 위한 자원이 부족한 경우에는 어떻게 하나요? 이건 다른 부분과 마찬가지입니다. 한 번에 모든 것을 할 수 없고 지금 가지고 있는 자원을 가지고 개선할 수 있는 부분을 조금씩 향상해 나가야 합니다.
예를 들어 문서 소유자를 명확히 하고 문서를 프로세스에 포함해 문서가 최신 상태로 계속 유지되는지만 체크하더라도 문서 품질은 향상될 수 있습니다.
https://youtu.be/90gaMmYseFY?si=mtIStPKi8K5HltJd
Michelle Irvine - Quantifying
www.flickr.com
