내 README를 따라 해보도록 사람들에게 돈을 지불했습니다

개발자들은 문서 작성에 서툽니다. 우리는 'RTFM(Read The F***ing Manual)'이라고 말하는 것을 좋아하지만, 종종 R에 대한 FM 자체가 없습니다. 기껏해야 반쯤 제대로 된 메모들, 일부 쓸모없어진 팁들, 그리고 같은 질문을 반복해서 하는 사람들로 가득 찬 황량한 포럼 링크가 전부입니다. 이것은 사용자들을 대하는 방식이 아닙니다.

저는 더 나은 방법이 있다고 순진하게 믿습니다. 이전에 쓴 것처럼, 여러분은 앉아서 실제로 README를 테스트해야 합니다. 새로운 Virtual Machine을 실행하고, 작성한 내용을 따라가 보면서 말이 되는지 확인해 보세요.

하지만 자신의 편견을 무시하는 것은 정말로 어렵습니다. 물론 당신은 특정 명령어가 sudo를 필요로 한다는 것을 알고 있고,
그리고 명백히 여러분이 -foo를 작성했을 때, --foo를 의도했다는 것도 알며,
모두가 나중에 재부팅해야 한다는 것을 압니다.

이러한 편견들을 어떻게 없애야 할까요? 저는 사람들에게 돈을 지불했습니다!

ActivityBot에 대한 NLnet 연구 지원서의 일부로, 저는 실제 사용자와 함께 설치 경험을 테스트하고 싶다고 말했고 그들에게 시간당 €25를 지불할 준비가 되어 있었습니다. Mastodon에 이 요청을 올리고 몇몇 사람들을 모아 비디오 통화를 했습니다.

형식은 간단했습니다. 저는 첫 실행 경험에 대한 피드백을 찾고 있다고 설명했습니다. 완벽하지 않다는 것을 알고 있었고 적극적으로 건설적인 비판을 원했습니다. 자원봉사자에게 화면 공유를 요청하고, 결정적으로 소리 내어 말하도록 했습니다. 그들이 무엇을 하고 있는지, 무엇을 이해하지 못했는지, 무엇이 혼란스러웠는지, 무엇에 기뻐했는지, 무엇에 좌절했는지 등을 말하게 했습니다.

저는 손으로 메모를 했고(기계에게 먹이를 주는 건 싫습니다), 제가 어떤 잘못된 가정을 했는지 몇 시간 동안 들었습니다.

제가 발견한 주요 내용들 중에는 다음과 같은 것들이 있었습니다:

• 데모 도구 링크가 잘못되었습니다.
• 어떤 사람들은 터미널에서 README를 읽었습니다.
• 파일 이름을 바꾼다는 것이 실제로 무슨 의미인가요?
• 숨겨진 파일을 이름 바꾸려면 어떻게 해야 하나요?
• 데모 도구가 웹에서 제공되어야 할까요, 아니면 사용자 로컬 머신에만 있어야 할까요?
• 왜 어떤 텍스트는 명시적으로 따옴표로 묶어야 하고 어떤 것은 그렇지 않은가요?
• 제 농담은 재미없고 적극적으로 혼란스럽습니다.
• 일부 기술 용어는 설명이 필요했습니다.
• 여러 섹션의 순서가 혼란스러웠습니다.
• 저는 소프트웨어가 실제로 무엇을 할지 설명하지 않았었습니다.
• 저에게는 기술적으로 흥미로웠던 전체 섹션이 다른 사람들에게는 완전히 혼란스러웠습니다.
• 모든 웹 서버가 권한(permissions)을 같은 방식으로 사용하지 않습니다.

그리고 그렇게 시작되었습니다!

매 세션마다 저는 사람들이 어려움을 겪었던 부분을 바탕으로 README를 업데이트했고, 다음 사람과 다시 테스트했습니다.

총합해서, 저는 여러 사람이 제 앞에서 비판하도록 하는 데 약 €150을 지불했습니다. 치료보다 싸죠?

누군가

ActivityBot의 README가 완벽해졌다고는 주장하지 않습니다. 전혀 그렇지 않지만, 이제 따라 하기가 명백히 더 쉬워졌습니다. 개발자들은 실제 사람들과 이야기해야 합니다. 만약 감당할 수 없다면 그들에게 돈을 지불할 필요는 없습니다. 하지만 당신의 지침을 따라 하면서 소리 내어 말해줄 몇몇 사람들을 찾아보세요. 저는 당신의 README가 훨씬 더 좋아질 것이라고 보장합니다.