▲

예제가 최고의 문서임

 (rakhim.exotext.com)
33P by GN⁺ 3일전 | ★ favorite | 댓글 8개
  • 개발자들이 문서를 검색할 때 95%는 간단한 예제만으로 충분하지만, 공식 소스에서 예제를 찾을 수 있는 경우는 5%에 불과
  • 공식 기술 문서는 기본적으로 해당 생태계에 깊이 몰입한 사람을 대상으로 작성되어, 여러 프로젝트와 언어를 오가는 개발자들에게는 컨텍스트 복원에 상당한 정신적 에너지가 필요
  • Python의 max() 함수 문서를 보면 함수 정의 문법과 개념을 이해하기 위해 필요한 사전 지식이 많지만, 간단한 예제 5줄이면 즉시 이해 가능함
  • Clojure 커뮤니티의 clojuredocs.org는 사용자 기여 예제를 통해 실용적인 문서를 제공하며, 관련 함수까지 포함하여 실제 활용도를 높인 모범 사례
  • 주요 소프트웨어 프로젝트조차 4가지 유형의 문서를 제공하는 경우가 드물어, 개발자들은 튜토리얼을 찾게 되는데 이는 안내가 필요해서가 아니라 예제가 필요하기 때문

문서 검색 시 예제의 중요성

  • 개발자들이 문서를 찾을 때 95%의 경우 단 한개의 예제만으로 충분
  • 그러나 공식 소스에서 예제를 찾을 수 있는 경우는 5%에 불과
  • 대부분의 공식 기술 문서는 생태계에 깊이 몰입한 사람을 기본 대상으로 작성됨
  • 많은 개발자들은 일상적으로 여러 "세계"를 머릿속에서 저글링해야 함
    • 프로젝트, 언어, 프레임워크 간 전환이 빈번
    • 컨텍스트를 복원하고 상황을 이해하는 데 상당한 정신적 에너지 소모

Python 문서 사례 분석

  • Python 3 문서의 max() 함수 예시
    • max(iterable, /, *, key=None): 가장 큰 항목 반환
    • 이후 5개의 짧은 단락으로 설명 이어짐
  • 이 문서를 이해하기 위해 알아야 하는 Python 지식
    • 함수 정의에서 *의 의미
    • 함수 정의에서 /의 의미
    • "positional-only parameter separator"의 개념
    • iterable의 개념
    • keyword-only arguments의 개념
    • key 파라미터의 일반적 의미
  • 텍스트를 읽어야 어떤 값을 전달하고 함수를 실제로 호출하는 방법 이해 가능

간단한 예제의 효과

  • 중요한 세부사항을 간결성을 위해 생략할 수 없다는 점은 인정
  • 그러나 많은 개발자들이 해당 페이지를 찾는 이유는 단순히 max 함수에 커스텀 정렬 함수(key)를 전달하는 법을 빠르게 찾기 위함
  • 아래와 같은 예시가 있다면 바로 원하는 정보를 얻을 수 있음 
    max(4, 6) # → 6  
max([1, 2, 3]) # → 3  
max(['x', 'y', 'abc'], key=len) # → 'abc'  
max([]) # ValueError: max() arg is an empty sequence  
max([], default=5) # → 5
  • 예제를 통해 쉽고 직관적으로 이해 가능

Clojure 커뮤니티의 모범 사례

  • clojuredocs.org는 Clojure 커뮤니티 기반 프로젝트
    • 사용자들이 내장 함수에 대한 예제 기여
    • 일상적인 코딩에서 필수불가결한 리소스
  • 예시 페이지들: into, spit, map 같은 것들 참고
  • 예제의 특징
    • 해당 함수뿐만 아니라 관련 함수들도 포함
    • 실제 활용도와 실용성을 높임

현재 문서화의 한계

  • 주요 소프트웨어 프로젝트조차 4가지 유형의 문서를 제공하는 경우가 드뭄
  • "Documentation" 링크 클릭을 주저하게 되는 이유
    • 대부분 간결하고 읽기 어려운 자동 생성 API 레퍼런스
  • 개발자들이 튜토리얼을 찾는 실제 이유
    • 안내가 필요해서가 아니라 예제가 필요하기 때문
    • 튜토리얼이 예제를 포함하고 있어 더 유용함
▲
sonnet 1일전  [-]

솔직히 자바, 파이썬 중심으로 해당되는 이야기인 것 같습니다. 자언어 우월주의나 패러다임적으로 고립된 문화가 강한 생태계기도 하죠.
파이썬을 기준으로는 잘 맞는 내용이지만 다양한 언어를 공부하다보면 5%는 상당히 과장처럼 느껴지네요.

답변달기
▲
kuber 1일전  [-]

코드가 곧 문서인 고랭으로 오세요~
저흰 README 없어도 테스트코드 까보고 개발합니다

답변달기
▲
howudoin 2일전  [-]

자바 계열과 객체지향 문화에서 유독 무의미한 설명 문장과 형식적 문서가 많았고, 그 분위기를 이어받은 파이썬 계열의 프레임웍들에서도 유독 예제가 빈약함.

무의미한 문서화의 예시
add(left, right) - 좌항과 우항을 더함

정작 중요한 파라미터의 데이터 타입이나 반환될 수 있는 예외나 결과값의 형태나 동작구조 같은건 설명하지 않음

c언어의 맨페이지 같으면 그냥 짧은 설명만으로도 함수와 파라미터 이름으로 유추해서라도 사용가능.

답변달기
▲
pjtco 2일전  [-]

저만 머리 나빠서 공식문서 이해 못하는줄 알았어요 ㅋㅋ
진짜 예제 던져놓고 설명만 쪼금 해주면 금방 이해되는걸.....

답변달기
▲
nemorize 2일전  [-]

PHP가 좋은 예시이자 최악의 예시가 되겠네요.

공식 문서에 사용자 기여 컨텐츠를 업로드 할 수 있어 다양한 코드 예시를 확인할 수 있다는 점에서 좋은 예가 되어주지만,

...PHP가 내장 함수들의 미묘한 BC들이 많고, 그 예제 기여가 죄다 호랑이 담배피던 시절 버전의 것들이라, 실제 작동과 미묘하게 다른 것들이 섞여있어 혼란만 가중시킨다는 점에서 최악의 예시...ㅋㅋ..ㅋ...

답변달기
▲
savvykang 2일전  [-]

예전 iOS나 Cocoa 개발문서를 보면 유즈케이스 섹션이 따로 있었는데 그게 맞는 문서화방법이지 않을까요? 예제와 함수 시그니처, 동작 설명 전부 필요합니다

답변달기
▲
aer0700 2일전  [-]

공식 docs의 빈약함을 예전에는 스택 오버플로와 구글링이 메웠으면, 요즘은 llm이 메우는 것 같네요.

답변달기
▲
GN⁺ 3일전  [-]
Hacker News 의견

  • 옛날 파이썬의 가장 좋은 점은 라이브러리 문서를 열면 함수의 인자와 반환값이 명확히 정리되어 있는 부분이었음. 요즘엔 많은 JavaScript나 파이썬 라이브러리 문서가 예제만 제공하는 경우가 많아 아쉬움. 빠르게 뭔가 만드려면 예제가 좋지만, 문제를 고치거나 라이브러리를 학습하려면 인자값 설명이 필수적임. 예제가 보너스인 건 좋지만, 그게 전부가 되어선 안됨

    • 사실 당신이 원하는 것은 타입 정의임. 타입 정의가 좋은 문서 역할을 함. 타입 시스템 도구가 이미 많은 정보를 에디터나 IDE에서 바로 보여주니, 직접 문서를 찾아 읽는 일은 줄어듦. 요즘 예제 중심 문서가 늘어난 건 그런 워크플로우의 변화 때문임. 어차피 타입 도구가 제공할 정보를 문서에 또 반복해 쓸 필요가 없단 판단에서임. 나는 문서를 볼 때 세부 인자보다는 '이 도구가 어떤 문제를 풀어줄 수 있나'에 더 관심이 많음. 예제가 그 가능성을 보여주는 데 탁월함. 특정한 문제를 풀고 싶을 때, 예제를 보면 그 도구가 도움이 되는지 빠르게 판단할 수 있음. --- 타입 시스템이 있다면 난 예제를 먼저 보고 싶음. 타입 시스템이 없으면 1) 불만족임. 2) 먼저 예제를 보고, 그 뒤에 세부 인자/반환/데이터 구조 설명을 원함

    • 좋은 문서는 둘 다 필요함. 먼저 세부 내용을 설명하고, 그 다음 다양한 예제를 더해 내용을 점검할 수 있도록 하면 됨. 때로 예제만으로 충분할 수 있지만, 옵션 조합이 너무 많으면 모두를 예제로 보여주는 건 거의 불가능임. 그래서 각 옵션에 대한 설명을 먼저 제공한 뒤, 최대한 다양한 케이스의 예제를 준비해서 독자가 응용할 수 있게 만들어야 함. 그리고 좋은 문서는 만들기 매우 어렵고, 요즘엔 정말 보기 힘든 것임

    • 나는 완전히 동의하지 않음. Javadoc 스타일 문서는 타입과 인라인 docstring 기반의 프로그래밍 문서임. 반드시 있어야 하지만, 굳이 웹으로 갈 게 아니라 코드 자체를 보는 것이 효율적임. 예제나 QuickStart 같은 가이드는 꼭 필요함. 그게 라이브러리의 진입 장벽을 낮춰줌. 코드만 보고는 API 사용법을 쉽게 알 수가 없음. 과거 많은 Java 라이브러리가 Javadoc만 제공해서 사용법을 몰라 불편했던 경험이 있었음

    • 잘 주석 단 예제가 최고라는 생각임. 하지만 전통적인 문서의 대체가 될 수는 없음

    • 혹시 다른 사람이 본인과 학습 스타일이 다를 수도 있다는 점을 생각해 봤는지 궁금함. 예제가 문서의 일부여야 한다는 것에 왜 저항이 있는지 이해를 못하겠음. 예제는 다양한 상황에서 맥락 전환의 마찰을 줄여주기 때문임

  • 유닉스 man 페이지도 예제가 절실히 필요함. 보통은 이미 툴을 잘 아는 사람을 위한 참조형으로만 쓰여 있어서 초보자에게는 전혀 도움이 안 됨. 좋은 문서는 두 가지 모두 필요함

    • 완전히 동의함. 모든 man 페이지 작성자분들께 conventional section인 EXAMPLE이 있다는 점을 상기시키고 싶음. man(1) 공식 문서 참고하면 좋음

    • 나는 그런 문제를 느껴본 적은 없음. 일단 코드를 만들어 보면서 명령어나 용어를 익히고, 에러 반환 코드와 그 원인, 파라미터 의미 등을 하나씩 살펴봄. 예제가 없어도 문서가 완전하면 충분함. 반면, 아무런 설명 없이 예제만 제공되는 건 진짜 최악임. 파라미터가 뭔지, 뭘 의미하는지조차 알 수 없는 문서가 어딨음?

    • 예전에 Stack Overflow에서도 비슷한 시도를 했다는 것이 좋았음. Stack Overflow Documentation이라는 이름으로 2016년부터 2017년까지 베타로 운영했었음. 예제 중심의 문서를 만들려 했지만 종료됨. 그래도 커뮤니티가 남긴 콘텐츠는 여전히 CC BY-SA로 공개돼있음

    • cheat.sh를 참고해 볼 것임. 나는 스크립트에서 curl cheat.sh/"$1"로 바로 사용함

    • 의외로 많은 man 페이지에 예제가 있다는 사실에 늘 놀람. 그래도 좀 더 종합적으로 개선될 여지가 많음

  • 예제는 초보자나 가끔 쓰는 사용자에게만 좋은 게 아님. 숙련자에게도 정규 문서, 즉 모든 파라미터 구성이 있는 문서가 필요함. 예를 들어, requests 문서는 항상 Google이 Quickstart 같은 예제만 잔뜩 있는 페이지로 보내서 불편함. HTTP GET은 누구나 알 수 있지만, 다른 옵션은 뭔지, timeout 처리나 raise_for_status가 204를 무시하는지는 찾기 힘듦. 둘 다 필요한데, 개발자 시간이 부족하면 우선 올바른 문서를 제공하는 쪽을 택하겠음. requests Quickstart 예제 링크

    • 예제를 보면 레퍼런스 스타일 문서보다 행동을 훨씬 더 쉽게 이해할 수 있음. 사람들은 이름부터 개념 정리, 문서 작성 모두에 약함. 최근에도 한 파라미터가 특정 조건에서만 동작하는 문제로 몇 시간 고생함. 코드를 파악하자니 너무 복잡했고, LLM조차 문서가 없는 파라미터라고 잘못 알려줬음. 결국 예시 코드를 만들어가며 원하는 동작을 찾는 게 가장 효율적이었음. 예제는 여러 중요한 내용을 축약해서 빠르게 검증할 수 있음. 반면 API 문서는 모든 내용을 전부 다루려다보니 관리도 힘들고 핵심만 전달하지 못함. 그리고 명확하지 않은 이상, 라이브러리의 동작은 절대 신뢰하지 않음. README에서 명확하게 행동을 보여주거나 타입으로 규정된 게 아니면 언제든 변경될 수 있음을 염두에 둠. 결국 호출 코드를 최대한 방어적으로 짬

    • 예제는 초보자뿐 아니라 모두에게 중요함. 5초짜리 예제로 한 시간치 문서 읽기와 실험의 효율을 누릴 수 있음. git의 몇몇 문서가 특히 그런데, 본질적으로 단순하지만 설명이 어려운 함수도 똑같음. 개발자가 한 가지만 만들 수 있다고 해도, 예제와 문서를 둘 다 내놓을 정도의 여력은 충분함. 둘 다 제공해야 하고, 워낙 자명한 경우만 예외로 둘 수 있음

    • 동의함. 좋은 문서는 거의 프로그램 동작 전체를 명확히 정해줘야 하고, 예제로만 그 역할을 하기는 힘듦

    • 둘을 동시에 가질 수 있음. 예제와 기술 문서는 양립 불가가 아님

    • occasional users 이야기는 바로 내가 하는 얘기임. 프로젝트, 언어, 프레임워크를 오갈 때마다 맥락을 회복하고 어떤 상황인지 이해하는 데 상당한 정신적 비용이 듦

  • Perl을 두고 뭐라고 하는 사람이 있겠지만, Perl 문서는 진짜 도움 됨. 항상 SYNOPSIS 섹션이 앞에 있어서 바로 쓸 수 있는 예제 코드가 나옴. 그 다음에 설명, 레퍼런스, 추가 예제가 따라옴. 예시: bigrat 문서, Archive::Tar 문서. 프로젝트 문서를 쓸 땐 Perl 스타일을 참고하는 게 좋음. 그리고 그 스타일 자체도 잘 정리돼 있음

    • 2000년대 초반에 Perl을 썼다가 2014년에 우연히 다시 쓰게 됐는데, 완전히 다시 기억나는 느낌이었음. 뭔가 Larry Wall의 언어학적 관점과 태도 덕분인지 참 인상 깊게 남게 됨. 수학적 정밀성 때문은 아니지만, 뭔가 '친구와 대화하는 느낌'이 강함

  • 둘 다 필요함. 예제를 보면 바로 감을 잡고, 통합하기 쉽고, 세부 파라미터와 설정값 설명은 도구의 복잡한 문제 해결과 전체 이해를 도와줌. 둘 중 하나라도 빠지면 정말 불편함. 단, 아주 단순한 라이브러리는 예제가 모든 내용을 설명할 수도 있음

    • 예제와 레퍼런스 문서 모두 필요함. 가능하다면 REPL 환경도 추가하는 것이 좋음. 예제를 바로 수정하고 테스트할 수 있으면, 문서가 부족해도 많은 단점이 커버됨

  • Diátaxis 프레임워크는 문서에는 다양한 종류가 있고 각각 용도가 있음을 잘 보여줌. 어느 것이 '최고'가 아니라, 각기 다른 필요에 따라 쓰이는 게 중요함. Diátaxis 공식 사이트

    • 이 얘기가 맨 위에 있어야 할 정도임. 이렇게 많은 토론을 거친 후에야 Diátaxis 언급이 나와서 좀 답답했음. 예제는 문서의 핵심이긴 해도, 독자적인 '문서 종류'라기보단 중요한 '문서 기법'에 가깝다는 관점임

    • 맞음! 예제(혹은 튜토리얼)는 시스템 교육의 한 축임. 누가 처음 만들었는지 확실하진 않지만, 링크가 기사 마지막 저자의 링크와 유사함: > "메이저 프로젝트도 4가지 종류의 문서를 다 갖추는 경우는 드물다. 그래서 ‘Documentation’ 링크를 클릭하는 게 망설여질 때가 있다" 나는 설명 위주의 문서가 좋음. 구조나 동작 이유를 이해하면 예제든 튜토리얼이든 쉽게 받아들이게 됨. 고수 기술 작가나 교육자가 이 틀을 처음부터 잘 잡아주면 효과가 큼. 반면 API 레퍼런스는 주로 래퍼나 호환 구현 시에 가장 필요함. 원래 많은 프로젝트가 비공개 API 레퍼런스에서 시작했고, 문서화도 그걸 외부로 공개하는 일이었음. divio documentation 시스템 참고

    • Diátaxis 개념은 훌륭함. 단, 실제 프로젝트에 넣기는 쉽지 않음. 프로젝트마다 필요한 문서 비율이 다르고, 모든 형태를 한 웹사이트에서 제공하는 건 비효율적임. 커뮤니티의 성장과 전문성에 따라 그 비율도 계속 달라짐. 좀 더 실질적인 방법이 있었으면 함. 문서화는 어려운 과제고, 언젠가는 더 나은 해결책이 나오기를 바람. 지금으로선 시간과 전문성 투자에 따라 품질이 결정되는데, 대체로 그게 부족한 게 현실임

  • Unity와 Unreal에서 이런 문제를 정말 자주 느낌. 특히 Unreal의 노드 문서는 노드의 스크린샷과 명칭만 다시 적어놓고, 실제로 어떻게 쓰는지는 전혀 안 알려줄 때가 많음. Unity도 어떤 함수의 제대로 된 활용법을 알고 싶어서 문서를 찾지만, 아예 내용이 없는 경우도 많음. 가능하면 나라도 Unity 문서에 예제를 기여하고 싶을 정도임

    • Unreal의 형편없는 문서화는 나에게도 엄청난 시간 낭비임. 그들은 '코드가 곧 문서'라는 분위기지만, Blueprint용 '노드 스크린샷 설명'은 정말 웃음이 나올 수준임

    • £JOB 관련, 사람들이 $job을 쓸 때 그게 돈을 버는 직업(task)의 의미에서 쓰는 건지, 단순 변수명에서 따온 건지 궁금함. 이쯤에서 내 세상관이 흔들림

  • 나는 ImageMagick을 자주 쓰는데, 항상 예제를 찾아서 구글링했었음. 그래서 개인적으로 정리한 노트를 작은 명령어 예제 모음집으로 합침. 각 인자에 대한 설명도 상세히 추가했음. 이 블로그 글에서처럼 예제만 있는 게 아니라 설명도 같이 필요하다고 생각함. 아직 초안 단계지만, 리사이즈, 최적화, 레이어링처럼 일상적 작업엔 이미 매우 유용함. 내 노트 공개 링크

  • 코드 예제는 유닛 테스트로 실행해서 문서가 낡거나 깨지는 걸 방지할 수 있음. 자연어로는 불가능한 장점임

    • 이제 LLM이 발전하면서, 예를 들면 API 문서의 정확성 검증도 시도할 수 있을 것임

  • 급진적 의견: 특정 메서드의 스펙이 시그니처와 몇 가지 대표적인 예제만 봐도 직관적으로 유추되지 않는다면, 그 메서드는 너무 많은 기능을 하려는 것임. 발이 묶이는 추상화나 복잡한 예외도 배우고 싶지 않음

    • 아니라고 생각함. 예제는 해당 메서드뿐 아니라 '다른 메서드와 어떻게 같이 써야 하는지'도 보여주기 위해 필요함. 메서드 시그니처만 보고 다 유추할 수 있다고 해도, 설정 누락이나 준비 과정, 결과 처리 등 중요한 부분을 놓치기 쉬움. 그래서 예제가 필수임
답변달기