사람들에게 돈을 주고 README를 따라 해보게 했습니다

AI 요약

문서 작성자는 README를 처음부터 끝까지 직접 따라 해보면 오류를 찾을 수 있다고 생각했지만, 작성자에게는 명령어의 숨은 전제나 빠진 설명이 당연해 보이기 쉽습니다. 이 편향을 줄이려고 ActivityBot 설치 과정을 실제 사용자에게 맡겼습니다. Mastodon에서 참가자를 모집했고, 한 시간에 25유로를 지급했습니다. 전체 비용은 약 150유로였습니다.

사용자가 문서를 따라가는 모습을 관찰했습니다

참가자에게 첫 실행 경험을 평가해 달라고 설명한 뒤 화면을 공유하도록 했습니다. 무엇을 하는지, 무엇을 이해하지 못했는지, 어디서 혼란스럽거나 불편했는지 소리 내어 말해 달라고 요청했습니다. 작성자는 메모를 손으로 적었고, 각 세션이 끝날 때마다 README를 고쳐 다음 참가자에게 다시 시험했습니다.

빠진 전제와 혼란스러운 설명을 찾았습니다

시험 과정에서 데모 도구 링크가 잘못된 사실을 발견했습니다. 일부 사용자는 README를 터미널에서 읽었고, 파일 이름을 바꾸는 방법이나 숨김 파일을 바꾸는 방법부터 막혔습니다. 데모 도구를 웹에서 제공해야 하는지 로컬에서 실행해야 하는지도 질문으로 나왔습니다. 어떤 텍스트에는 따옴표가 필요한 이유, 기술 용어의 뜻, 웹 서버마다 권한을 다루는 방식이 다르다는 점도 설명해야 했습니다.

문서 구성 순서가 혼란스러웠고, 소프트웨어가 실제로 무엇을 하는지 설명하지 않은 점도 드러났습니다. 작성자에게는 흥미로운 기술 설명 한 부분이 참가자에게는 거의 이해되지 않았습니다. 농담도 오히려 혼란을 줘서 고쳤습니다. 작성자는 README가 완벽해졌다고 주장하지는 않지만, 전보다 따라가기 쉬워졌다고 말합니다.

자동 점검과 실제 사용자 피드백

작성자는 LLM에 다양한 사용자를 흉내 내게 하는 대신 실제 사람과 대화하고 싶다고 설명합니다. 사람은 문서가 혼란스럽다는 점뿐 아니라 지루하거나 재미없다는 반응도 드러냅니다. GOV.UK에서 기술 문서를 쓸 때도 다른 사람이 문장을 다듬고, 맞춤법 검사기로 찾지 못하는 오류를 잡아냈다고 덧붙입니다. 사용자가 말하는 동안 목소리에서 느껴지는 답답함 역시 고쳐야 할 부분을 알려줬다고 합니다.

Hacker News 반응

• @nkrisc — UX 분야에서 하는 사용성 테스트와 거의 같습니다. 만든 절차를 누군가가 진행하는 모습을 옆에서 지켜보는 방식입니다. 보통은 참가자마다 결과물을 고치지는 않지만, 일반적인 전자상거래 흐름이 아니라 특수한 README를 시험하는 경우라면 괜찮을 수도 있습니다. 다만 엄밀한 방식은 아닙니다.
• @WhyNotHugo — 빠른 시작과 전체 설치 안내 모두 PHP-FPM 설치와 설정, HTTP 서버가 PHP-FPM을 백엔드로 사용하도록 설정하는 단계가 빠졌습니다. PHP로 서비스를 운영해 본 사람에게는 익숙한 작업이겠지만, 처음인 사람은 알아서 해결해야 합니다.
  • @edent — 어디까지 설명해야 하는지가 어려운 문제입니다. README는 Git으로 파일을 내려받는 방법도 안다고 가정합니다. 사용자가 어떤 사람인지에 따라 안내 범위가 달라집니다. PHP 사용 여부를 확인하도록 돕는 방법을 생각해 보겠습니다.
  • @layer8 — 설치 안내에는 보통 사전 준비 항목이 있어야 합니다. 준비물을 설치하는 방법까지 설명할 필요는 없어도 목록은 있어야 합니다.
• @BoppreH — 제 README 기준은 깨끗한 컴퓨터에서 명령을 순서대로 실행하면 소프트웨어가 유용한 작업을 하게 만드는 것입니다. 여기에는 git clone도 포함합니다. 이미 웹 서버가 있다면 건너뛰라는 설명을 붙이면 됩니다. 운영 환경에 적합하지 않은 지름길을 쓰면 눈에 띄게 경고합니다. 간단한 명령만으로 절차를 만들면 숨은 전제를 줄이고 소프트웨어를 시험하기도 쉬워집니다.
• @badsectoracula — 작성자가 실제로 돈을 낸 이유는 사람과 대화하기 위해서였고, README 검사는 부차적이었던 셈입니다. 제일 먼저 떠오른 생각은 LLM에 README를 확인하고 지시를 따라 보게 하는 것이었습니다. 괜찮은 LLM이라면 안내가 충분한지 살펴보고 개선점을 제안할 수 있습니다. 다만 직접 작성하게 두지는 않겠습니다.
  • @amirkhanian — 에이전트와 사람은 서로 다른 문제를 잡습니다. 제 에이전트 검토자는 조이스틱을 누른 채 화면을 확대하면 작동이 깨지는 실제 버그를 찾았습니다. 하지만 게임이 지루하다고 말해준 사람은 없었습니다. 집까지 캐릭터를 걸어가도 아무 일도 일어나지 않아, 휴대전화로 직접 해본 제가 지루하다고 느꼈습니다.
• @sbarre — 기술 문서는 해당 도구에 익숙한 전문가가 쓰는 경우가 많습니다. 그런데 그 전문성 때문에 의도한 독자도 같은 수준의 지식을 갖췄다고 생각하고 작성합니다. 그러면 독자가 따라갈 수 없는 가정과 논리의 도약이 문서에 생깁니다.
• @astura — 이건 편향 문제가 아닙니다. 문서를 시험하는 사람이 문서를 읽고 그대로 따르지 않는 문제입니다. 저는 문서를 단계별로 실제로 따라 하며, 고객이 할 것처럼 명령을 복사해 붙여 넣어 제대로 작동하는지 확인합니다. 문서를 제대로 따라가면 이런 문제를 찾을 수 있습니다.
• @tilemarch — 사람도 훌륭하지만 AI도 도움이 됩니다. 저장소나 스테이징 문서를 준비하고, 서로 다른 정체성과 특성을 준 에이전트 20개에 작업을 시키면 사람과 비슷한 곳에서 막히거나 빠진 단계를 지적합니다. 다만 에이전트는 문서가 혼란스럽다고 말하지 않고 확신에 차서 잘못된 행동을 합니다. 통화 중인 사람이 “잠깐, 이게 무슨 뜻이죠?”라고 하는 데에는 25유로를 낼 만한 가치가 있습니다.
• @sccxy — 대부분의 README에는 스크린샷이 있어야 합니다. 명령줄 도구라도 스크린샷이 있으면 어떤 모습인지 더 쉽게 알 수 있습니다.
• @chanux — 기술 문서에 산문과 이야기를 길게 쓰곤 했는데, 다시 읽어보니 저 자신도 읽기 싫은 글이었습니다. 이제는 간결하고 직접적으로 쓰려고 합니다. 인간미를 더하는 표현을 넣더라도 핵심 내용을 방해하지 않을 때만 사용합니다.
  • @shevy-java — 짧고 정확하게 쓰는 편이 대체로 낫습니다. 많은 프로젝트에 작동하는 예제가 없다는 점이 특히 불만입니다. 예제가 없으면 새 사용자가 프로젝트를 배우도록 신경 쓰지 않는다는 인상을 줍니다.

원문: shkspr.mobi / 번역·요약: Trawling