README를 실제 사용자에게 검증받다

핵심 요약

• 개발자들은 문서 작성을 제대로 하지 않는데, 저자는 ActivityBot README 작성 시 실제 사용자 피드백을 받기로 결심했다.
• NLnet 그랜트 지원 과정에서 €25의 보수를 지급하기로 약속한 후 마스토돈에서 모집한 사람들과 화상 통화를 진행했다.
• 테스트 방식은 단순했는데, 자원자가 화면을 공유하며 실시간으로 README를 따라하면서 무엇을 이해하지 못했는지, 뭐가 혼란스러웠는지 말하도록 했다.
• 저자는 손으로 메모를 취하며 잘못된 가정들을 파악했다: 데모 도구 링크 오류, 터미널에서 README 읽기의 문제, 파일명 변경 방법 설명 부족, 따옴표 필요성 불명확, 농담이 혼란을 야기, 전문 용어 미설명, 섹션 순서 혼란, 소프트웨어의 실제 기능 미설명, 기술적으로 흥미로운 부분이 사용자에게는 복잡함, 웹 서버 권한 설정 다양성 미반영 등이었다.
• 각 세션 후 발견된 어려움을 바탕으로 README를 수정한 후 다음 사람과 재테스트하는 방식으로 진행했고, 총 €150을 지출했다.
• LLM으로 시뮬레이션하지 않은 이유는 실제 사람과의 상호작용이 필요하기 때문이며, 사용자의 좌절감을 목소리에서 감지하는 것이 실수 수정의 핵심이다.
• GOV.UK 기술 문서 작성 경험에서 동료의 검토가 불필요한 표현을 제거하고 오류를 잡아냈다는 점을 강조했다.
• 저자는 ActivityBot README가 완벽하지는 않지만 이제 따라하기 훨씬 쉬워졌다고 확인했고, 개발자들에게 실제 사람과의 대화를 통해 문서를 개선할 것을 권장했다.