지난 2년간 적용해 본 가독성 지표 기반 문서화에 대해 설명합니다. 이번 강의를 위해 오픈소스 도구도 만들었다고 하네요.
가독성 지표를 도입한 이유는 독자들의 인지 부하를 줄이기 위함이었다고 합니다. 2년 전에는 테크니컬 라이터나 스타일 가이드 없이 제각각 만들어진 문서가 있는 상태여서 이를 전반적으로 개선하고 문서화 작업을 다시 진행해야 했습니다. 이 과정에서 리뷰어의 참여가 중요한데 리뷰어(개발자)들의 인지 부하를 줄이면 좀 더 효율적으로 작업하 수 있을 것이라 판단했다고 합니다.
기존 CMS 도구를 사용할 수도 있었지만 가독성을 평가하기 위한 데이터 수집에 최적화된 도구가 필요했기 때문에 직접 도구를 만들어 사용하기로 했습니다.
GitHub 저장소에 문서를 커밋할 때 가독성 점수를 체크하고 이전 문서보다 점수가 낮은 경우에는 등록을 보류합니다. 어떤 문제가 있는지 확인하고 개선할 수 있는지 검토합니다.
문장을 간결하게 써야 하는데 논문을 작성해 본 경험이 있는 경우에는 학술적인 글이 가지는 스타일을 벗어나기 어렵다고 합니다. 때문에 가독성 지표에서 문장의 길이나 문장 내의 단어수를 체크해서 이를 개선할 수 있게 합니다.
https://github.com/Rebilly/lexi
모든 지표를 새로 만든 것은 아니고 기존 기술 문서의 가독성을 측정하는 항목을 검토하고 이를 반영했습니다. 7개의 지표를 검토했는데 다른 지표와 반대되는(아마 이걸 수정하면 이게 나쁜 점수로 반영되는) 2개를 제외한 5개를 사용하고 있다고 합니다. 그리고 5개의 지표에 가중치를 두어 하나의 단일 지표로 만들었다고 하네요.
- Flesch Reading Ease https://readable.com/readability/flesch-reading-ease-flesch-kincaid-grade-level/
- Gunning Fog https://readable.com/readability/gunning-fog-index/
- Automated Readability Index https://readable.com/readability/automated-readability-index/
- Dale Chall Readability Score https://readable.com/readability/new-dale-chall-readability-formula/
- Coleman Liau Index https://readable.com/readability/coleman-liau-readability-index/
플레이그라운드로 제공하는 페이지도 흥미롭네요. 위에서 언급한 5개의 지표를 실시간으로 확인해볼 수 있습니다. 아쉽게도 어느 부분을 수정해야 하는지 가이드를 제공해주지는 않습니다.
https://rebilly.github.io/lexi/
Q&A에서 나온 이야기인데 가독성 지표가 사용자의 인지 부하를 얼마나 감소했냐는 것에 대해서는 아직 검증이 되지 않았다고 합니다. 어느 정도 유용하다는 것을 경험을 통해 얻기는 했는데 이게 실제 사용자 인자 부하에 대한 지표와 연결되지는 않았습니다.
https://youtu.be/BRZqQ6AjPc0?si=owDKxajQjsncyO0h
MetricDrivenDocumentation
www.flickr.com
