요약
README는 처음 보는 사람이 직접 따라 해 봐야 고칠 곳이 드러납니다.
영국 개발자 테렌스 이든의 글입니다. 재단 지원금으로 ActivityPub 도구인 ActivityBot을 만들면서 설치 안내서를 실제 사용자에게 시험하겠다고 약속했고, 그 과정과 결과를 정리했습니다.
왜 중요한가
- 문서를 쓴 사람은 어떤 명령에 sudo가 필요한지 같은 자기 전제를 알아차리기 어렵다는 점을 실제 시험으로 보여 줍니다.
- 한 사람에 25유로, 모두 150유로 안팎만 들여도 문서를 훨씬 따라 하기 쉽게 고칠 수 있다는 사례입니다.
핵심 내용
- Mastodon에서 지원자를 모은 뒤, 화상 통화로 화면을 공유하며 생각을 소리 내어 말하게 했습니다.
- 한 사람을 시험할 때마다 README를 고치고, 고친 문서로 다음 사람을 다시 시험했습니다.
- 이 소프트웨어가 무엇을 하는지조차 설명하지 않았다는 점이 드러났습니다.
- 틀린 데모 링크, 숨김 파일 이름 바꾸기, 들쭉날쭉한 따옴표, 어색한 농담도 걸림돌이었습니다.
- LLM(대규모 언어 모델)으로 사용자를 흉내 내자는 제안에는 사람 목소리의 답답함이 고칠 곳을 알려 준다며 반대했습니다.
HN 반응
- 여러 이용자가 UX 분야의 사용성 테스트(실제 사용자가 쓰는 모습을 관찰하는 시험)와 같다고 짚었고, 5~6명만 시험해도 문제 대부분이 나온다는 경험담이 이어졌습니다.
- 자기만 볼 문서도 몇 주만 지나면 알아보기 어렵다는 고백이 나왔고, 몇 년 뒤 지친 자신을 독자로 삼아 쓰라는 조언이 뒤따랐습니다.
저도 데이터 리포트를 만드는 정확한 절차 같은 걸 잊지 않으려고 저 혼자 볼 README를 가끔 씁니다.
불과 몇 주만 지나도 그게 얼마나 알아볼 수 없는 글이 되는지 놀랍습니다. 머릿속에 다 들어 있을 때는 모든 게 분명하고 매끄럽고 설명이 필요 없는데, 맥락을 잊고 나면 아무것도 이해가 안 됩니다.
대부분의 사람은 언어로 생각하지 않고, 개념으로 훨씬 많이 생각합니다. 문제는 글을 쓸 때 우리가 개념으로 생각하고 있다는 걸 거의 깨닫지 못한다는 겁니다. 그런 개념은 저절로 떠오르기 때문에 알아채지 못하거든요.
학교에서 이 때문에 어려움이 많았습니다. 하나는 다른 사람이 이해할 수 있게 글로 풀어 쓰는 일이었고, 다른 하나는 교육에서 흔히 쓰는 설명을 읽을 때 언어가 부정확하다 보니 같은 문장을 서로 다르거나 때로는 상충하는 여러 의미로 받아들일 수 있다는 점이었습니다.
결국 개념을 설명하면서 다른 해석의 여지를 거의 남기지 않는 건 어려운 일입니다.
이게 LLM이 쓴 글, 적어도 코딩 모델이 쓴 글에서 짜증 나는 점으로 드러납니다. 늘 "이 테스트는 이것만 확인하고 저것은 확인하지 않습니다" 같은 말을 하거든요. 대개는 뻔한 얘기이거나, 읽다 보면 "그 다른 것도 확인하는 테스트여야 하는 거 아닌가?" 싶어집니다.
저는 언어로 생각하는 사람이라, 제 글에서 뭔가를 행간으로 읽어 주길 기대하는 사람들과 자주 엇갈립니다. 제 글은 제가 뜻하는 바를 정확히, 그 이상도 이하도 아니게 전하려고 쓴 거거든요.
네, 100% 공감합니다.
깔린 속뜻이나 상징 같은 건 없으니, 이메일은 쓰인 그대로 읽어 주세요.
저는 열다섯 살쯤에 아판타시아가 됐고, 그 뒤로 몇 년 동안 비기술직 사람들과 전화나 이메일로 소통했습니다.
영어는 포르투갈어 같은 언어에 비해 정확하게 쓰기가 정말 지독하게 어렵습니다.
그리고 LLM은 헛소리를 너무 길게 늘어놓아서, 대체 무슨 얘기를 하는 건지 맥락을 따라가는 게 불가능합니다.
아판타시아가 "됐다"고 하신 게 궁금합니다. 계기가 된 사건이 있었나요, 아니면 어떻게 알게 되셨나요?
제가 알기로 아판타시아는 최근 10~20년 사이에야 널리 알려졌거든요(물론 지금 연세가 어떻게 되시는지는 전혀 모르지만요).
저는 고등학교 때 알게 됐는데, 80~90년대였고 정확히 그 이름으로 안 건 아니었습니다. ASVAB를 봤는데 "종이를 반으로 두 번 접고 일정한 무늬로 구멍을 뚫은 다음, 펼쳤을 때 어떤 그림이 나오는지 고르시오" 같은 문제가 나왔고, 저는 그게 말도 안 되게 쉽다고 생각했습니다. 머릿속으로 이미지를 그리지 못하는 사람에게는 어려운 문제라서, 그런 능력을 시험하려고 넣은 거라고 들었습니다.
아판타시아가 된다는 말은 처음 들어 봅니다. 어떻게 그렇게 된 건가요?
일부러 반대 입장에서 말해 보자면, 다른 해석의 여지를 거의 남기지 않고 개념을 설명하는 건 무의미하기도 합니다. 상대방의 해석에 신경 쓰지 않는다면 대체 왜 그 사람과 얘기를 하는 겁니까? 정말 그 작업이 결정론적이라면 자동화하면 되죠.
규칙이 어떤 것인지 알아야 어떤 규칙은 구부려도 되고 어떤 규칙은 깨도 되는지 알 수 있습니다.
제가 겪는 문제는, 읽자마자 경험이 부족한 사람이 만들었고 같은 결과에 이를 더 낫고 빠르고 싼 방법이 있다는 걸 아는 절차를 따르라는 요구를 받을 때입니다. 그런데 절차에서 벗어나면 곤란해집니다. 검증되고 승인된 것이 그 절차이기 때문입니다. 절차를 벗어났다가 나중에 일이 예상대로 안 풀리면 책임을 뒤집어쓸 수도 있습니다.
학교, 특히 배움은 결정론적이지 않습니다.
대부분의 일을 자동화할 수 있다고 해도, 사람의 학습은 거기에 해당하지 않는 것 같습니다.
네, 제가 하려던 말이 그겁니다. 해석이 핵심이기 때문에 결정론적이지 않은 거죠. 학습자가 자료를 자기 안에 녹여 내는 방식이 바로 해석입니다. 해석하지 않으면 배우는 게 아니라 그냥 외우는 겁니다.
그러니 교사는 개념을 설명할 때 생기는 모호함을 받아들여야 합니다.
사람은 둘이 섞여 있습니다. 알고리즘만 배우는 건 어렵고, 개념을 잡으려면 어느 정도의 초기 데이터가 필요한데, 그 양은 사람마다 꽤 많이 다를 수 있습니다.
주니어는 결국 자라서 시니어가 되고, 그 자동화를 유지보수할 책임도 그 사람이 지게 되니까요.
게다가 정말로 해석에 맡기는 일이라면 "버스 팩터"가 1이 됩니다. 누군가 휴가라도 가면 일정에 실질적인 위험이 생기는 거죠.
이런 문서를 쓰는 건 일종의 "근육"이라서 경험이 쌓일수록 나아진다고 생각합니다.
예를 들어 문서를 직접 쓰고, 자신이나 다른 사람이 그 문서를 쓰는 걸 지켜보다 보면 사람들이 대체로 무엇을 이해하고 그걸 어떻게 전달해야 하는지 감이 잡힙니다.
"도그푸딩"도 할 수 있습니다. 한 사람이나 한 팀이 문서를 쓰고 다른 사람들이 그걸 따라 해 보는 겁니다. 이걸 빠르게 반복하면 짧은 시간에 아주 좋은 문서를 만들 수 있습니다.
자기가 보려고 쓰는 문서에서 정말 도움이 됐던 방법이 하나 있는데, 지금의 나를 조금 바꾼 버전의 나를 위해 쓰는 겁니다.
독자는 여전히 본인일 수 있습니다. 하지만 그 사람은 4~5년 더 나이를 먹었고, 그동안 살면서 별별 일이 있었을 테고, 기억할 것도 더 많아졌고, 피곤하고, 참을성도 줄었습니다. 자기 자신을 상대로 고고학 발굴을 해야 한다는 게 짜증스럽고, 지금의 당신처럼 자기 기억력이 훌륭하다고 믿는 철없는 애송이를 곱게 보지 않을 겁니다.
그 사람을 위해 쓰면 문서가 나아집니다.
(눈치채셨겠지만 저는 이미 그 사람입니다. 그리고 이 순환이 두 번은 더 남았을까 봐 두렵습니다.)
요즘 올라오는 글의 절반이 이런 식이에요. "Gleam 2.0, 우리가 배운 것" 하길래 홈페이지에 들어가 보면 "Gleam은 당신의 Fork를 위한 Tribble입니다! (아래로 스크롤) Gleam Enterprise 자격이 되는지 확인해 보세요!" 이러거든요.
이게 이렇게 당연시되는 게 좀 웃겨요. 더 명확하게 쓰면 시장에서 분명히 유리할 텐데요?
아니면 Fork에 붙일 Tribble이 필요한 사람들은 홍보 문구만 읽어도 단번에 깨달음을 얻으려나요.
마케팅 이메일이나 (더 심한 건) 대기자 명단에서도 그래요. "좋은 소식입니다, 정식 오픈했어요!" 하는데, 아니 그런데 당신들 누구였죠?
맞는 말이에요.
그런데 또 이런 댓글이 달리는 글도 많이 봐요. "Tribble이 뭔지도 모르는데 Gleam이 뭘 하는 건지 어떻게 알아요? 블로그에 아무 설명도 없네요! 어떻게 이렇게 자주 쓰는 용어를 설명도 안 하고 글을 쓸 수가 있죠?"
그런데 링크된 블로그 글은 www.tribbleworld.com의 Daily Tribble News 섹션에 올라와 있고요.
이건 UX 디자인 분야에서 말하는 사용성 테스트와 아주 비슷합니다.
닐슨 노먼 그룹(Nielsen Norman Group)에 좋은 입문 글이 있습니다: https://www.nngroup.com/articles/usability-testing-101/
HN 분들께 이런 주제가 흥미로운가요?
저는 코딩과 디자인을 섞은 전공을 했습니다.
어디선가 읽은 기억이 있고 제 경험과도 맞는데, 첫 번째 사용자가 문제의 50%를 잡아내고 5명이면 90% 가까이 잡아낼 수 있다고 합니다. 그러니 사람을 직접 쓰는 테스트는 값을 매길 수 없을 만큼 가치 있을 뿐 아니라, 얻는 효과에 비하면 꽤 저렴합니다.
제가 일했던 UX 직장에서는 어디서나 대체로 참가자 6명으로 사용성 테스트를 했습니다. 온라인 사용성 테스트 도구가 널리 퍼지기 전이었고, 사무실에 실험실(매직미러와 관찰실까지 갖춘)이 있었습니다. 같이 일한 UX 리서처들은 하나같이 기존 연구와 개인 경험에 비추어 말씀하신 대로라고 했습니다. 5~6명을 넘기면 효과가 눈에 띄게 줄어들어서 굳이 할 가치가 없다는 거였죠.
아마 그쪽에서 배우셨을 겁니다! 그쪽 테스트 결과로는 첫 번째 사용자가 잡아내는 비율이 31%입니다.
https://www.nngroup.com/articles/why-you-only-need-to-test-with-5-users/
https://www.nngroup.com/articles/how-many-test-users/
네, 아마 그럴 겁니다. 감사합니다!
QA와 버그 사냥만의 얘기가 아닙니다.
타깃 사용자층을 직접 고용하면, 그 사람들은 자신과 크게 다를 수 있고, 그러면 갑자기 언어가 그들을 헷갈리게 한다거나 색 조합이 다른 의미로 받아들여진다거나, 본인에게는 지극히 자연스러웠던 흐름을 그들은 도무지 이해하지 못한다는 걸 알게 됩니다.
저도 "이거 사용성 테스트나 사용자 조사 같은데"라고 쓰려던 참이었습니다.
하지만 우리는 필요할 때마다 같은 것을 새로 발견하는 모양입니다.
기술 문서에서 제가 본 가장 큰 문제는, 전문성을 이유로 해당 도구나 제품의 숙련 사용자에게 문서 작성을 맡기는 경우가 많다는 점입니다.
그런데 아이러니하게도 그 사람들은 정작 대상 독자가 아니라 자기와 전문성 수준이 같은 독자를 상대로 문서를 쓰게 됩니다.
그러다 보니 대상 독자가 따라갈 수 없는 가정과 논리 비약이 문서에 가득하게 됩니다.
저는 흥미롭다고 봅니다. 여기에는 부업(혹은 본업)으로 뭔가를 만드는 사람이 많고, 저처럼 UX 배경이 없어서 모범 사례를 모르는 사람도 많을 텐데 그런 제품에는 명확한 UX가 필요하니까요. 어쨌든 저는 링크를 바로 눌러 봤습니다...
정말 형편없는 README를 많이 읽어 봤습니다. 프로그램이 뭘 하는 것인지조차 안 알려 주는, 정말 심각한 것들요. 자기 이름이 뭔지 알려 주는 걸 깜빡한 README도 하나 기억납니다.
하지만 이건 결국 기본적인 사용성 테스트입니다. 저는 지금도 직장에서 "아, 시작이라도 하려면 C# 런타임을 설치해야 해요" 같은 문제를 마주칩니다. 지금은 빌드 체인에서 그걸 확인하도록 고쳐 놓았습니다.
자기 맥락에서 벗어나기가 어렵다는 건 압니다. 하지만 문서란 바로 그걸 하는 것입니다.
"run"이라는 단어에는 정의가 600개가 넘고 "set"에는 400개가 넘는데, 다른 업계에 있는 최종 사용자가 당신의 맥락에 신경 써 주길 기대하시는 겁니까? 그 사람들의 맥락을 신경 써야 하는 건 우리 몫입니다. 그들이 문제를 해결해 달라고 우리에게 돈을 내고 있으니까요.