▲

초보 개발자인 내가, 당신(개발자)이 나를 위해 쓴 튜토리얼을 읽는 방법

 (anniemueller.com)
1P by GN⁺ 7시간전 | ★ favorite | 댓글 1개
  • 초보자가 개발자들이 작성한 기술 튜토리얼을 읽을 때의 혼란과 장벽을 유머러스하게 묘사한 글
  • 개발자들이 흔히 사용하는 전문 용어와 약어는 초보자에게는 전혀 맥락 없는 ‘외계어’처럼 들림
  • 튜토리얼의 설치 단계, 파일 경로, 터미널 명령어 등이 지나치게 복잡하거나 생략되어 이해하기 어려움
  • 글쓴이는 개발자 시각에서는 당연한 설명이 초보자에게는 수 시간 검색과 시행착오를 요구하는 장애물이 된다고 지적함
  • 이 글은 튜토리얼을 쓰는 개발자들에게 초심자의 관점에서 설명을 더 친절하고 명확하게 해야 함을 상기시켜줌

글의 배경과 문제의식

  • 글쓴이는 개발자가 아닌 초보자로서 개발자들이 작성한 튜토리얼을 읽으며 겪는 경험을 서술함
  • 튜토리얼에 등장하는 기술 용어와 도구 이름이 무슨 뜻인지 전혀 감이 잡히지 않는 상황을 풍자적으로 표현함
  • 예: Hoobijag, Snarfus, Shamrock portal 같은 가상의 기술명을 사용해, 초보자 눈에는 모든 것이 복잡하게 보인다는 점을 강조함

원문 번역

“안녕! 나는 개발자야. 나의 관련 경험은 이래: 나는 Hoobijag로 코딩하고 가끔 jabbernocks도 쓰고, 물론 ABCDE++++도 하지 (하지만 절대 ABCDE+/^+는 아니야, 그건 말도 안 되지? 하하!) 그리고 Shoobababoo로 일하는 걸 좋아하고 가끔 kleptomitrons도 다뤄. 나는 Company[1]에서 Shoobaboo 관련 코드를 하게 되었고, 그게 나를 Snarfus로 이끌었어. 자, 시작해 보자!

이 튜토리얼에 대하여

나는 처음 Snarfus로 아주 간단한 것[2]을 하기 시작했는데, 쓰면 쓸수록 잠재력을 보게 되었어! chromus가 좀 뒤엉켜 있지만, 사실 굉장히 다목적이야. 그래서 나는 hoobastank 대신 quagmire로 pintafore를 argyling하기 시작했지! 미쳤지, 알아. 하지만 어느 정도는 작동했고, 사실 꽤 재미있었어… 큰 장벽을 만날 때까지: fisterfunk가 shamrock portal과 전혀 대화하지 않고, Snarfus로 beep-boops를 보내주지도 않는 거야! 물론, 그게 무슨 의미인지 알지[3]— 이제 전체 hoob-터널이 gramelions로 막혀 버렸어. 용납할 수 없지.

거의 포기할 뻔했지만, 그때 깨달았어: backside Snarfus stagnator를 backside shamrock Klingon troglodyte emulater에 연결하면 괜찮아! 모든 게 beep-boops와 ding-dongs 하면서, 드디어 튜토리얼의 실제 주제에 도달한 거야. 그리고 원하는 방식으로 아주 간단한 것을 할 수 있게 되었지! 꽤 멋지지[4].

그래서 설정 방법은 이래:

  1. 터미널에서 ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas 입력
  2. 이제 folder/hidden/deep/in/the/file/system/surprise!.file로 가서 파일 내용을 복사해. 만약 그곳에 없다면, library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file에 있을 수도 있어
  3. 다시 터미널로 돌아와 파일 내용을 붙여넣고, 64A786AGR45JAR; rdja;jg [[]][[]][[]][[]]][()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!! agjlkargji;lwej;OI [ASRGASG[]ASGDASG[]EAEadgasg[]EAGE[edaga][]ahgr-0-0=-0-=0-=0=0-0=-0-=0=-0-=0=-0=-0!!! 입력
  4. Boop![5]
  5. Snarfus를 열고 방금 만든 파일을 업로드해
  6. 그냥 재미 삼아, chronostatiomatrix의 sham을 해제하고 싶으면 —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][] 실행해도 돼. 선택 사항이야
  7. 끝!

어떻게 되는지 알려 줘. 혹시 누가 이 방식을 GewGawGamma나 ometer2.7과 함께 쓰는지도 궁금해.”

각주 설명

  1. 유명한 회사 같은데 나는 알지 못함
  2. 전혀 간단하지 않음
  3. 무슨 뜻인지 모름
  4. 멋지긴 한데 이해는 못 했음. 그래도 당신이 할 수 있어서 다행임
  5. 처음 3단계는 약 7시간과 193번의 검색이 필요할 것. 하지만 Boop!에 도달하면 굉장히 짜릿함

마무리

  • “이건 그냥 재미로 쓴 글임. 지식을 공유하고 튜토리얼을 작성해주는 모든 분들께 진심으로 감사함.”
▲
GN⁺ 7시간전  [-]
Hacker News 의견

  • 누군가에게 최소한의 지식만 있는 상태로 문서를 따라 해보게 하고, 옆에서 말없이 지켜보는 접근법을 적극 추천함. 이때 전혀 도와주지 말고 그저 관찰만 하면 됨. 그 과정에서 사용자가 어디서 막히는지, 저자 본인은 너무 익숙해서 미처 생각 못한 부분이나 설정이 누락된 점 등 다양한 문제점을 발견할 수 있음. 만약 사용자가 별다른 스트레스 없이 목표를 달성하면 문서가 통과한 것임. 그렇지 않으면 실패한 지점을 하나도 빠짐없이 기록하고, 각각을 개선한 후 새로운 사람으로 다시 테스트하는 과정이 필요함. FAANG 같은 대기업 문서도 이 기준을 통과하지 못하는 걸 사용해 보았음. 우리 조직이 높은 기준을 세운 데 정말 감사하고 있음. 이런 방식으로 문서를 만들면 반복적 미팅, 지원 요청, 영상 통화가 줄어들고, 사용자가 스스로 문제를 해결할 수 있게 됨

    • Apple의 문서를 사용할 때 이런 문제가 자주 발생한다는 경험이 있음. 문서 내 정의가 그냥 이름만 반복해서 설명 없이 넘어가는 경우가 많고, 좀 더 구체적으로 써줘야 함
    • "말하지 말고 관찰만 하라"는 규칙이 쉬워 보이지만 실제로는 참지 못하고 설명하거나 힌트를 주는 사람들이 많았음. 심지어 직접 마우스를 잡은 경우도 있음. 이런 인간적인 반응을 피하려면, 중립적인 진행자(모더레이터)가 별도로 있고 저자/개발자는 관찰만 하는 것도 도움이 됨. 하지만 '그저 지켜보기' 기술을 익히는 것이 중요하고, 더 발전하고 싶으면 "think-aloud protocol(생각을 말하기 프로토콜)"을 알아보기를 추천함
    • 대부분의 기업 팀 온보딩 문서는 질이 형편없어서, 실제 업무 부담을 미리 보여주는 창구임. 최근 합류한 세 개 팀은 문서가 거의 없거나 오래되어서 직접 관련자를 찾아다니며 필요한 접근권한이나 배포 파이프라인 정보를 얻어야 했고, 그 과정에서 새로운 문서를 작성하지만 시스템이나 권한이 추가되면 바로 구식이 되는 악순환임. 단 한 팀만 이틀 만에 필요한 환경을 다 세팅해주었고 그 경험이 최고였음. 지금은 새 devex 팀에서 문서 환경 자체를 개선하기 위해 노력 중임
    • 형편없는 세팅 문서를 읽으면서 온보딩을 하는 건 정말로 스트레스를 10배는 더 받는 느낌임. 항상 신입사원이 경험한 문제를 최초 기여로 바로 수정하게끔 장려해왔음. 신입들은 아무런 맥락이 없으니 최고의 리뷰어 역할을 할 수 있음
    • 우리 조직도 같은 워크플로를 씀. 경험이 적은 사람이 문서를 따르도록 하고, 그 뒤 모두가 지속적으로 문서를 개선하길 장려해옴. 오랜 경험자로서는 생기는 '맹점'을 신입들이 잘 집어낼 수 있기 때문임. 내 경험상, 사용자의 자신감을 관리하는 것도 매우 중요하다는 교훈을 얻음. 그래서 "이 셸 명령을 실행하세요" 같은 단계를 안내할 때 기본적으로 몇 가지 섹션을 접어서 제공함(예: 성공적으로 실행된 출력 예시, 무시 가능한 경고, 발생 가능한 에러 목록과 처리 방법, 복잡한 명령어 설명 등). 어떤 단계는 한 페이지만큼 긴 설명이 붙기도 하지만, 온보딩 시에 이런 상세함이 실제로 엄청난 도움이 되고 있음

  • 블로그 포스트 제목은 "비개발자인 내가, 개발자인 당신이 쓴 튜토리얼을 읽는다"였지만, HN 제목은 "초보 개발자인 내가..."로 바뀌었음. 비개발자와 초보 개발자는 전혀 다름. 예를 들어 인사팀이나 완전 비전공자에겐 내부 용어나 개념도 아예 생소할 수 있음. 이 경우 개발자가 완전히 동떨어진 설명을 썼다면 비판받아도 마땅함. 반면 초보 개발자는 어렵더라도 새로운 용어나 개념을 직접 알아보고, 시간이 지나면 새로 들어온 초보자를 위해 문서까지 업데이트할 수도 있음

    • 참고로 글 제목을 "비개발자"로 제출했으나 중간에 "초보 개발자"로 바뀐 것임. 글쓴이는 기술 비전문 블로거이고, 웹사이트나 CSS를 다루려면 여러 기술 문서를 참고해야 했을 것임. 사이트 발행 및 비전문가용 문서 부재에 대해 논의하는 게 더 적합할 수도 있었다고 생각하지만, HN 커뮤니티가 다른 방향으로 논의를 끌고 가는 것도 괜찮음
    • 이 구분은 매우 중요함. 글쓴이 Annie가 스스로 "콘텐츠/문서 관련 일"을 하고, CSS 취미도 있다고 밝히니 "비전문 취미 개발자"층임. 점점 더 커질 영역이라 생각함. 초보/비개발자를 포함하는 튜토리얼을 쓸 때는 "cd ~/.snarfus(폴더 없으면 만들어라)" 같은 문구에도 아주 간단히 부연 설명 하나만 추가해도 충분함. 나 역시 과거 Debian 설치할 때 작은 설명 하나가 엄청난 도움이었음
    • 내가 프로그래밍에 입문할 때 감명을 받았던 사이트는 "FromZero"였음. 비개발자를 대상으로 IDE 설치부터 콘솔 열기까지 차근차근 설명해줬고, 생소한 용어는 "나중에 다룰 예정이니 지금은 신경 쓰지 마세요"란 식으로 안심시켜줘서 최고였음. 물론, 문서 작성은 시간과 노력이 많이 들어가니 때로는 일부 설명만 있는 것도 없는 것보다 낫다고 생각함. 초보 개발자를 위한 문서는 비개발자 수준의 배려로 작성해야 한다고 봄
    • 어떤 이들은 무엇이든 아주 쉽게 설명해주지 않으면 게이트키핑이라고 주장하고, 본인이 힘들다고 느끼지만 사실 사전 지식 없이 무엇이든 바로 이해할 수는 없다는 점을 간과한다고 느낌
    • 만약 초보 개발자를 위한 튜토리얼이고 전문 개발자를 대상으로 한 글이 아니라면, 일일이 "Hoobijag", "shamrock portal" 같은 개념을 다 설명해주길 기대하는 게 이상함. 사실 우리 모두 처음엔 모르는 용어를 구글링하면서 익혀왔음

  • 대부분의 튜토리얼은 비개발자용이 아니라 동료 개발자끼리 정보를 교환하는 것에 가깝고, 학술 논문처럼 특정 지식 집단을 위한 문서와 비슷한 포지션임. 이런 방식도 나쁘지 않음. 오히려 내가 과거 기록해둔 문서도 다시 찾아보기 좋음. 그래서 초심자를 위한 코스·교재가 따로 존재함. 만약 튜토리얼이 매번 3만 자 전체 배경 설명부터 시작해야 한다면, 아무도 끝까지 안 읽을 것임. 반대로 더 많은 배경설명을 넣어도 누군가에게는 여전히 부족하게 느껴질 수 있음

    • 아들(17세)이 프로그래밍에 관심 큰데, 최근에 public/private/internal/static 개념 + 재귀까지 알려줬음. 내심 다음에 어떤 반응이 있을지 기다리는 중임
    • "튜토리얼이 대부분 비개발자용이 아니다"라는 주장에 동의하지 않음. 이번 튜토리얼 헤드라인 자체가 비개발자를 의도하고 있다는 점을 분명히 하고 싶음. 오픈소스 프로젝트를 설치하려다 고생하며, 아주 기초적인 설치 가이드라도 초보자가 따라할 수 있도록 쉽게 만들어야 한다는 목소리가 꼭 필요함. 사소한 단계를 빼먹으면 익숙하지 않은 분야에서는 몇 시간도 버릴 수 있음
    • 오히려 문서를 모두를 위해 더 친절하게 쓰는 것이 나쁘다고 생각하지 않음. 좋은 문서는 초보자뿐만 아니라 개발자에게도 유용함. 접근성 높은 문서가 없는 이유는 단지 약간의 노력을 더 들이기 싫기 때문이라 봄. 또, 개발자 문서는 논문과 달리 너무 간략하게 쓰거나 쓰는 이도 읽는 이를 신경쓰지 않아서 생기는 문제임. 결국 결과적으로 전문가 외엔 쓸모 없는 문서가 되어버림. 이건 실패임
    • 초보자를 위해 맥락을 차근차근 쌓아올리는 식의 문서가 필요함에 동의함. 다만, 요즘 DX(개발자 경험)를 "쉬운 것" 위주로만 개선하고 기존의 유용했던 로그나 에러 메시지 검색 기능 등을 희생해서, 오히려 초보자만 겨냥하고, 기존 유저는 쓰기 불편해지는 경향이 있음
    • 오늘날 튜토리얼은 실제로는 "내가 X 프로젝트에 기여했다"는 이력 관리를 위한 글이 더 많아 보임. 차라리 글쓴이가 3개월 후에 다시 자신의 튜토리얼을 따라 해 보면 빠진 내용이 확실히 눈에 띄어 큰 개선이 될 것임

  • 많은 테크니컬 라이터가 '지식의 저주'를 제대로 인지하지 못함. 예전에 WoW(월드 오브 워크래프트) 길드를 운영했던 경험이 있음. 40명이 동시에 모여 던전에 진입하고 협동해서 여러 보스를 상대해야 하는데, 아주 작은 실수 하나로 전체가 죽을 수 있음. 그래서 모두가 Teamspeak에 모여 전략을 사전에 충분히 설명했음. 이때 가장 큰 교훈은 "내가 뭘 말하는지 상대방은 모른다고 가정하라"와, "한번 말한 것도 반복하라"는 것임. 대부분 모르는 게 있어도 끼어들어 질문하지 않으므로, 계속 '내가 무슨 용어를 말하고 있는지', '이 개념을 모를 수도 있다'고 스스로에게 질문하면서 설명을 곁들이는 습관이 엄청난 효과를 냈음. 이런 소통 경험이 테크니컬 커뮤니케이션에도 그대로 적용되고, '지식의 저주'를 넘어서려는 노력을 몸에 익히면 타인의 이해도를 높일 수 있음

    • 예전 레이드 길드에서 18살짜리 길드장이 성인들을 여러 시간대에서 불러 모으고, 분배나 전략, 일정까지 모두 원만하게 조율하는 걸 보고 "이 친구는 바로 매니저로 취직해야 마땅하다"고 느꼈음
    • 40명 래이드 운영 경험이 있으면 누구나 프로젝트 매니저로서 최상급 역량을 갖게 됨. 이건 그야말로 '집나간 고양이 무리'를 군더더기 없이 이끄는 일임

  • 많은 프로젝트 홈페이지나 GitHub README는 마치 "이 글을 읽는 사람은 이미 다 안다"는 식의 태도로 작성되어 있음. 내가 문서를 볼 때 '이 도구가 왜 필요한지', '무슨 문제를 해결하는지', '비슷한 다른 툴과 어떻게 다른지', '지금도 계속 사용되는지', '장단점 비교까지 스스로 판단할 수 있도록 재료를 주는지' 같은 세심함이 더해지면 좋겠음. 단 5분만 투자해서 "아무리 초보라도 무엇을 궁금해할까?"를 생각해서 그걸 써주면 접근성이 크게 올라감. 여러 해를 투자해서 만든 프로젝트라도, '사용자가 찾은 줄도 모르게 귀찮아서 포기하게 되는 상황'이 반복되는 건 정말 안타깝다고 생각함. 그리고 문서 종류별 역할을 잘 이해하는 것도 중요함. https://diataxis.fr/가 좋은 첫출발점임

    • ROS(로봇 소프트웨어) 분야에서 READMEs가 정말 부족해서 늘 스트레스를 느꼈음. 프로젝트 이름 말고는 힌트가 없어서, 용도 파악조차 어려운 경우가 비일비재함. 오픈소스만의 문제가 아니라 직장에서도 동일한 경험이 있었고, 내가 나서서 README에 설명을 추가하는 유일한 사람 같음. 과거 모노리포 시절이 오히려 더 행복했음
    • 개발자들이 애정과 노동으로 만든 툴인 건 이해하지만, 문서만 잘 챙겨도 진입 장벽이 훨씬 낮아질 것임. 게다가 스택을 구성하는 다른 컴포넌트 문서마저 어려우면 학습 곡선이 기하급수적으로 가팔라짐
    • 예전 HN에 심지어 '무엇인지'조차 쓰지 않은 프로젝트가 올라온 적도 있음

  • 문서 작성 시 가장 중요한 것은 '대상 독자의 지식 수준'을 명확히 정하는 것임. 기준선을 높게 잡거나 낮게 잡아도 상관없지만, 기반선에서 너무 벗어나면 일부 독자는 반드시 불만을 갖게 됨. 이런 상황에서 변명을 택할 수도, 해결책을 추구할 수도 있음. 사실 AI, 구글, 서적 등으로 요즘은 어떤 것도 바로 찾아볼 수 있음. 'Shoobababoo가 뭔지' 또는 '왜 quagmire를 쓰는지' 궁금하면 검색하면 됨. 물론 문서가 가능하면 외부 정보 없이 최대한 자급자족하게 작성되는 게 이상적이지만, 세상은 그 친절함을 반드시 제공해주지는 않음

    • 그래서 다양한 설정 가이드에서 "이제 exe파일 더블 클릭 후 계속(next)"부터 시작하는 경향 같은 게 더 문제임. 가이드의 기반선 설정이 정말 중요함
    • 나는 내부 민감 시스템용 문서를 주로 작성하는데, 때로는 문서 맨 앞에 "이 가이드는 x, y, z 사용법을 이미 안다고 가정함. 그렇지 않으면 이 작업을 하면 안 됨"이라고 명확하게 밝힘. 접근 권한도 제한되어 있지만, 만에 하나 DR 시나리오 등으로 익숙하지 않은 사람이 쓸 수 있으니 '이 정도도 이해 못하면 절대 하지 마라'는 경계선을 일부러 남기기도 함

  • 내가 오랜 기간 멘토링하며 강조한 원칙은 "아는 것은 나누는 게 최선"임. 뭔가 알고 있다면 꼭 설명해주고, 만약 이미 알고 있는 사람에게 말했더라도 그저 확신만 더해준 셈이고, 반대로 몰랐다면 큰 도움이 됨. 가끔 너무 장황하다는 불평이 나오지만, "이건 혹시라도 신입이나 고객, 매니저가 볼 수도 있어서 그 분들을 위한 것이었다"고 말하면 대부분 이해해줌. 이 원칙은 개발, 리포팅, 인사관리 등 모든 영역에 통함

    • 물론 이미 알고 있는 것을 설명받는 걸 극도로 싫어하는 사람도 있음. 신호대잡 비율이 너무 나쁘면 오히려 소통 자체가 저해될 수 있음
    • 내가 아들에게 당구를 가르치는 경험에서도 비슷함. 경계심을 버리고 팀원 간 팁을 아끼지 않는 문화가 성장에 매우 도움 됨. 멘토링에서는 정답을 주기보다 질문을 통해 스스로 찾아가게 유도하면, 본인이 깨달을 때 진짜 발전이 일어남
    • 모든 사람에게 일일이 알려주는 것은 "mansplaining"이라고 오해받거나, "모든 것을 아는 척한다"는 식으로 정치적으로 위협이 될 수 있음. 회사에서는 그냥 서로가 질문할 때만 답변하도록 하는 것이 더 안전할 때도 있음

  • 최근 Gitlab에서 DigitalOcean Kubernetes에 앱 배포를 해보니, 3~4개의 서드파티 도구를 무슨 일을 하는지 설명 없이 구현해야 했고, 명령줄에 입력할 이름이나 경로도 직접 알아서 넣어야 했음. 무엇이 기준이고 뭘 맞춰야 하는지도 설명 없음. Docker 실력이 꽤 있음에도 이런 도구들의 문서는 차라리 없는 편이 나을 정도로 불친절했음

  • 내가 책쓰기를 그만두고 튜토리얼 웹사이트를 만든 주된 이유는, 튜토리얼을 더 많은 이가 접근할 수 있도록 다양한 인터랙티브 도구(<abbr> 요소 등)의 도움을 받을 수 있어서임. 그럼에도 불구하고, 오늘날 웹 콘텐츠가 여전히 종이책의 기능에 머물러 있어 답답함. 클릭, 호버, 영역 접기, 영상, 사용자 반응 등 수많은 기능이 있는데도 여전히 벽처럼 긴 텍스트만 넘쳐남. 심지어 OP조차, 각주 클릭 시 페이지 맨 아래로 스크롤하는 방식을 쓰는데, 그건 웹의 잠재력을 제대로 활용하지 못했다는 느낌임

    • 방금 블로그 업그레이드에 도전하는 중인데, 이런 방식(인터랙티브하게 잘 만든 튜토리얼)을 잘하는 사이트를 추천해줄 수 있다면 고마움

  • 사실 튜토리얼의 대부분은 비개발자도, 개발자도 아닌 '불필요한 긴 텍스트' 뒤에 결국 중요한 한두 단계를 건너뛴 경우가 많음. 본인은 남에게 설명하듯이 글을 쓰는 게 어렵다는 점이 가장 큰 원인임. 자기 머릿속에서만 알고 있던 내용을 글로 풀어내진 않으면, 독자는 절대 알 수 없음. '튜토리얼' 대신 '요리책(cookbook)' 방식처럼 써야, 실전에서 쓰기 좋고, 버전업 후에도 쓸모없어지는 것을 막을 수 있음

    • 아이러니하게도, 요즈음 온라인 레시피(쿠킹북)가 비개발자 블로그보다도 훨씬 더 쓸데없는 잡설이 많은 경우가 많음
답변달기