— DX, Documentation, API, 개발자 경험, 문서화 — 3 min read
다음은 개발자 경험 (DX)을 좋게 만드는 데에 대한 제 의견입니다. 프레임워크와 같은 몇 가지는 DX라는 범위를 벗어나서 더 넓게 적용될 수 있다는 점을 주의하세요.
가능한 한 빠르게 온보딩시키기: 개발자가 창의적인 작업 흐름을 유지할 수 있도록 하려면 가능한 빨리 작업을 시작하도록 지원해야 합니다. 프레임워크와 라이브러리가 빠르게 시작할 수 있도록 최적화하세요. 예를 들어, npx create-next-app이나 brew install bat과 같은 명령어로 빠르게 시작할 수 있게 만들어야 합니다. 개발자에게 빠른 반복과 빠른 피드백 루프를 제공할 수 있도록 최적화하세요.
업그레이드 쉽게 만들기: 주요 버전 변경이 있을 때 변경이 “폭발적인 범위”를 제한해서 의존성 업데이트를 쉽게 할 수 있게 해야 합니다. 이상적으로 변경 사항은 메이저 버전에 도착하기 전 수개월의 리드 타임을 가지고 옵트인(opt-in, 역: 새로운 변경 사항이나 기능이 기본적으로 활성화되지 않고, 사용자가 필요한 경우에만 활성화하거나 선택할 수 있는 것. 사용자가 불필요한 변화에 영향을 받지 않고 사용자 스스로 정의할 수 음)으로 시작해야 합니다. 그리고 메이저 버전에는 코드를 자동으로 마이그레이션하고 문제가 되는 변경 사항을 수정하는 데 도움이 되는 코드모드(codemods, 코드 변환을 실행하는 스크립트)를 포함해야 합니다.
유용한 오류 메시지: 적용할 수 있다면 오류 메시지에 하이퍼링크를 포함하여 오류 해결 방법에 대한 더 많은 맥락을 제공해야 합니다. 당신이 제공하는 도구는 코드를 입력할 때 피드백을 제공해야 합니다. 런타임 또는 컴파일 오류가 발생하기 전에 더 빠르게, 더 낫게(예. 타입 체크, 린트) 말이죠. 개발자가 '어떻게 해야 하는지' 고민하게 만들지 말아야 합니다.
강력한 기본값과 규칙: 소프트웨어를 구축하는 '올바른 방법'에 대한 의견을 가져야 합니다. 예를 들어, 라우팅 설정에 대해 고민하지 않도록 하세요. Next.js의 파일 시스템 기반 라우팅을 사용하세요. 컴파일 및 번들링을 구성하지 않도록 하세요. webpack, swc, vite, esbuild을 사용해서 훌륭한 기본 값을 설정하세요.
탈출구 제공: 강력한 기본 설정을 제공하는 동시에 개발자가 필요에 따라 이를 무시하거나 수정할 수 있는 방법(탈출구)이 있는지 확인해야 합니다. Next.js의 초기에 성공한 이유 중 하나는 프레임워크를 벗어나지 않고 webpack을 쉽게 재정의할 수 있었기 때문입니다. 반면에 Create React App(CRA)는 이젝팅(ejecting, 역: 프로젝트나 도구의 내부 설정을 외부로 노출하거나 개발자에게 더 많은 제어 권한을 부여하는 작업) 후에 craco와 같은 도구가 필요했습니다.
의존성을 통해 위험 줄이기: npm i next를 실행하면 npm에서 13개의 종속성만 설치됩니다. 나머지 종속성은 빠른 설치 시간과 향상된 보안을 위해 Next.js에 내장됩니다. 향후에는 Next.js를 설치할 수 있는 단일 바이너리로 만들고 싶습니다.
코드로 시작하기: 개발자들은 코드를 작성하고 싶어합니다. 시작점으로 코드 예제를 제공하세요. 중요한 내용을 감추지 마세요.
문제 해결(aka: 질문에 답하라): 개발자는 질문, 어려움, 문제에 대한 답을 찾기 위해 문서를 찾습니다. 여러가지 방법(비디오, 텍스트, 튜토리얼, 가이드 등)으로 답을 제공해서, 개발자들이 자신에게 맞는 방식으로 해결책을 학습하게 만들어야 합니다.
자동화 된 문서: API를 문서화할 때는 '진리의 원천(source of truth)'인 코드에서 문서를 생성해서 동기화 된 상태를 유지하는 것이 좋습니다. 예를 들어, Vercel의 API 문서는 OpenAPI 스펙에서 자동으로 생성됩니다.
이상적인 상황(happy path) 말고: 문서는 작업을 완료하려는 개발자들을 위한 참고 가이드입니다. 이는 종종 에러를 검색하고, 복붙할 수 있는 해결책을 찾는 것을 의미합니다. 문제에 대한 임시 방편(workaround)이나 트릭(hacks)도 문서화하는 것이 중요합니다. 개발자들이 좌절하도록 내버려두기 보다는 제품의 결함을 인정하고 막힌 상황을 해결해주는 것이 더 낫습니다.
훑어보기에 최적화하기: 현실적으로 얘기해보죠. 우리는 모두 훑어봅니다. 특히 개발자 문서를 읽을 때 말이죠. 내가 겪고 있는 문제를 해결하기 위해 코드 블록으로 눈을 돌려 해결책을 찾습니다. 최고의 DX를 제공하기 위해 코드 스니펫에 유용한 주석을 추가하고 원하는 기능/API의 여러 옵션이나 변형을 보여주는 것을 고려하세요.
정확하게: 기술적인 용어와 관용구를 피하세요. 약어를 사용한다면 첫 번째로 사용할 때 풀어서 쓰세요. 독자가 그 용어를 알고 있다고 가정하지 마세요. 문서는 초보자와 전문가 모두에게 접근 가능해야 합니다. 접을 수 있는 "심층 탐구(deep dive)" 섹션에 전문가에게는 도움이 되지만 이상적인 구현에는 중요하지 않은 내용을 넣는 것을 고려해 보세요.
점진적으로 복잡성 노출하기: 처음 사용자 경험은 간결하게 유지하고 더 복잡한 기능에 대해서는 개발자들이 제품을 사용하면서 점진적으로 알 수 있게 하세요. 개발자들이 구현을 시작할 때 전체 플랫폼을 학습하기를 기대하는 것은 현실적이지 않습니다