README를 실제 사람에게 따라 하게 한 저자, 참가자에게 €25씩 주고 설치 문서 고쳐
- 저자는 ActivityBot 설치 경험을 시험하려고 Mastodon에서 모집한 참가자에게 1시간당 €25을 지급하고 화상 통화로 총 약 €150을 지출함
- 참가자들은 화면을 공유하고 소리 내어 말하는 방식으로 따라 했고, 데모 도구 링크 오류, 섹션 순서 혼란, 설명 없이 쓰인 농담 등 12개 문제가 드러남
- 매 세션이 끝나면 README를 즉시 수정하고 다음 참가자로 다시 테스트하는 방식으로 반복함
- 저자는 LLM으로 사용자를 흉내 내는 대안을 거부하고 실제 사람과의 대화에서 얻는 피드백이 핵심이라고 주장함
- 저자는 README가 완벽해졌다고 보지 않지만 따라 하기가 훨씬 쉬워졌다고 평가하며, 돈이 없으면 지인 몇 명에게 소리 내어 따라 해 보게 하라고 권함
Hacker News opinions
이모지 많은 README 보면 그냥 뒤로 가기 누름. 이모지 골라내는 데 인지 부담이 더 크더라.
저자 테스트에서는 참가자 절반쯤이 이모지를 좋아했고 한 명만 싫어했다는데, 표본이 작아서 참고만 하면 될 듯함.
이모지가 많으면 LLM으로 만든 프로젝트일 가능성이 높다고 봄. 사람이 기능 설명마다 이모지를 골라 붙이는 경우는 드묾.
이거 사실 UX 사용성 테스트랑 똑같음. 참가자한테 보상 주는 건 정상인데, 참가자마다 문서를 고치는 건 엄밀하진 않아도 틈새 문서라면 괜찮을 듯.
README에 php-fpm 설치하고 웹서버에 연결하는 0단계가 빠져 있음. PHP를 안 써본 사람은 그걸 몰라서 막히더라.
PHP 프로젝트면 필요한 버전이나 확장 요구사항은 최소한 적어줘야 함. 가능하면 컨테이너로 개발 환경을 통째로 묶는 것도 고려할 만함.
농담 쓰는 건 괜찮은데 프로젝트가 뭐 하는 건지 안 적으면 답이 없음. 멋진 이름에 설치 명령만 주르륵 있는 README 진짜 흔함.
Docker 프로젝트는 의존성 문제가 덜하긴 한데, 그래도 이상한 전제 조건이나 주문 같은 설치 절차가 붙어 있는 경우가 많음.
AI 에이전트가 README에 쓸데없는 내용을 잔뜩 채워 넣는 게 왜 그런지 궁금함. 원래 README도 엉망이었는데 AI가 기준선을 더 낮춘 건지.
예제 코드가 있는 프로젝트가 훨씬 잘 돌아가더라. 소스 코드가 다 설명해준다는 말은 문서를 귀찮아하는 핑계로 들림.