예제가 최고의 문서임

4 weeks ago 10

대부분 개발자들은 공식 문서에서 간단한 예제만 있으면 충분함을 느낌
공식 문서는 깊이 있는 사용자 위주로 작성되어 있어 이해가 어려움
언어와 프레임워크를 넘나들 때 문맥 전환에 많은 에너지가 소모됨
Python 3 공식 문서의 max 함수 설명은 초보자에겐 진입장벽이 높음
커뮤니티 중심의 clojuredocs.org 같은 예제 위주 사이트가 실무에 더 도움됨

예제가 부족한 공식 기술 문서 문제

개발자가 공식 문서에서 원하는 정보는 하나의 간단한 예제인 경우가 많음
그러나 실제로 공식 문서에서는 원하는 직관적 예제를 찾는 것이 쉽지 않음

공식 문서의 타깃과 난이도

공식 기술 문서는 기본적으로 생태계에 깊이 몰입한 사용자를 위한 형태로 작성됨
현대 개발자는 여러 프로젝트, 언어, 프레임워크를 넘나들기 때문에 늘 문맥 복원이라는 추가 부담이 생김

Python 공식 문서의 max 함수 예시

Python 3 공식 문서에서 max 함수의 정의는 다양한 문법적 지식을 요구함
- *는 무엇을 의미하는지
- /의 의미
- "positional-only parameter separator"의 정체
- iterable의 정의
- 키워드 전용 인자(keyword-only arguments) 개념
- key 파라미터의 용도
단순히 함수 호출 예제가 없는 경우, 사용자가 실제로 어떤 값을 전달할 수 있는지 파악이 어려움

간단한 예제의 효용

대부분의 개발자는 max 함수에 커스텀 정렬 함수(key)를 전달하는 법 등이 궁금함
아래와 같은 예시가 있다면 바로 원하는 정보를 얻을 수 있음

max(4, 6) max([1, 2, 3]) max(['x', 'y', 'abc'], key=len) max([]) max([], default=5)

이러한 예제를 보면 직관적인 사용법을 바로 이해할 수 있음

커뮤니티 예제 기반 문서 사이트의 장점

Clojure 생태계의 clojuredocs.org는 커뮤니티가 기여한 다양한 예제로 운영됨
실제 개발에 자주 필요한 예시와 연관 함수까지 함께 확인할 수 있어 높은 실효성을 가짐
여러 소프트웨어 프로젝트 공식 문서에는 다양한 관점(튜토리얼, API, How-to, 설명 등)이 부족한 경우가 많음
자동 생성된 API 레퍼런스보다 실제 코드 예제를 찾기 위해 튜토리얼을 선호하는 사용자가 많음

Read Entire Article