README를 제대로 검증하려고 사람들에게 돈을 지불했습니다
I paid people to try and follow my README
개발자들은 문서를 대충 쓰면서 RTFM이라고 말하지만, 정작 읽을 매뉴얼조차 제대로 갖춰지지 않은 경우가 많다. Terence Eden은 ActivityBot의 NLnet 그랜트 지원의 일환으로 참가자들에게 1시간에 €25를 지불하고 화면 공유와 함께 소리 내어 첫 실행 경험을 검증하게 했다. 그 결과 데모 도구 링크 오류, 터미널에서 README를 읽는 사용자, 혼란스러운 농담과 용어, 섹션 순서 문제 등 자신이 미처 인지하지 못한 잘못된 가정들이 드러났다. 각 세션 후 README를 수정하고 재검증하는 과정을 거쳐 총 €150을 지출했다.
사람들은 훌륭하다! 당신을 웃게 만들 수 있고, 고양이가 통화 중에 어슬렁거리며 들어오는 모습을 볼 수 있으며, 문제에 독특한 관점을 가져다주고, €25 상품권을 주면 정말 기뻐한다.
HN 토론
178- piro0919
반쯤 동의합니다.
저는 Claude Code로 앱을 만들고, Playwright로 AI가 UI를 클릭해가며 테스트하게 합니다. 그 정도면 명세대로 동작하고 깨진 게 없는지 확인하기에 충분하죠.
그런데 AI가 시도할 때와 사람이 시도할 때는 목적이 다르다고 생각합니다. 극단적으로 말하자면, AI는 UI를 위한 것이고 사람은 UX를 위한 것이죠. 물론 사람도 UI 문제를 찾긴 합니다. 제 음악 플레이어에서는 실제 iPad의 Safari에서 노래 재생이 막혔는데, 직접 써보고서야 발견했어요. 이 글에서 발견된 것들, 예를 들어 안 먹히는 농담이나 이 도구가 대체 뭘 하는지도 모르겠다는 것 같은 건 사람만 찾을 수 있는 영역입니다.
(이 글은 일본어로 썼고 AI로 번역했습니다.)
- bambax
> 하지만 자신의 편향을 무시하기란 정말 어렵습니다. 특정 명령에 sudo가 필요하다는 걸 당연히 알고 있고, -foo라고 썼을 때 --foo를 의미했다는 것도 뻔하며, 그 후에 재부팅해야 한다는 건 누구나 알죠.
저는 데이터 보고서를 생성하는 정확한 단계 같은 걸 기억하려고 나 자신을 위해 README를 쓰곤 합니다.
불과 몇 주만 지나도 그것들이 얼마나 이해 불가능해지는지 놀랍습니다. 모든 게 머릿속에 있을 때는 명확하고 유연하며 자명해 보이지만, 맥락을 잊어버리면 아무것도 말이 되지 않습니다.
- andai
>소프트웨어가 무엇을 할지 실제로 설명하지 않았죠.
요즘 보는 글 중 절반은 "Gleam 2.0. 우리가 배운 것" 같은 식이고, 홈페이지에 가보면 "Gleam은 당신의 Fork를 위한 Tribble입니다! (아래로 스크롤) Gleam Enterprise 자격이 되는지 확인하세요!" 이런 식입니다.
- bryanhogan
이건 UX 디자인 분야에서 말하는 사용성 테스트와 매우 비슷합니다.
Nielson Norman Group에 이에 대한 좋은 입문 자료가 있습니다: https://www.nngroup.com/articles/usability-testing-101/
HN 사람들에게 흥미로울까요?
저는 코딩과 디자인을 섞어서 전공했습니다.
- extralongdivisi
> 소프트웨어가 무엇을 할지 실제로 설명하지 않았죠.
"<정보 없는 이름>은 <언어>로 작성된 <유행어> <유행어>입니다."라는 패턴을 따르는 README를 얼마나 많이 읽었는지 셀 수도 없습니다. 사용해보거나 데모를 봐야만 그게 뭘 하는지 어렴풋이 알 수 있고, 그 데모조차 README를 통해서는 제공되지 않는 경우가 너무 많습니다.
- legacynl
이거 정말 좋네요. 대부분의 README는 그냥 형편없습니다. 가장 심각한 건 README가 프로젝트가 무엇을 하는지 명시하지 않을 때라고 생각합니다. 모든 프로젝트가 대중을 대상으로 하는 건 아니라는 걸 알지만, README 파일을 만들 만큼 수고했다면 왜 가장 기본적인 정보를 쓰는 10센티미터를 더 가지 않을까요?
다른 문제들:
* 오래된 (그래서 틀린) 정보
* 소개되지 않은 약어 사용 (일반적인 의미를 가진 약어라면 보너스 점수, 예: EG, NB, IE, ETC)
- trollbridge
이건 LLM이 정말 잘하는 것 중 하나입니다.
새 컨테이너나 샌드박스를 만들고, git 저장소를 복사하거나 스테이징 문서를 가리키게 한 다음, 무슨 일이 일어나는지 보세요.
- pinkmuffinere
> 내 농담은 재미없고 오히려 혼란스럽기만 하다.
:’)