[번역] 훌륭한 개발자 경험을 만드는 것은 무엇일까요?
'훌륭한 개발자 경험'에 대한 Vercel VP of Product의 생각
다음은 개발자 경험 (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)" 섹션에 전문가에게는 도움이 되지만 이상적인 구현에는 중요하지 않은 내용을 넣는 것을 고려해 보세요.
-
점진적으로 복잡성 노출하기: 처음 사용자 경험은 간결하게 유지하고 더 복잡한 기능에 대해서는 개발자들이 제품을 사용하면서 점진적으로 알 수 있게 하세요. 개발자들이 구현을 시작할 때 전체 플랫폼을 학습하기를 기대하는 것은 현실적이지 않습니다
API
- API 워크플로우를 깨지 마세요: API 버전은 매우 의도적이고 명시적이어야 합니다. API를 변경할 때는 과도한 의사 소통을 통해 개발자들이 새 버전으로 업데이트할 충분한 시간을 주는 것이 좋습니다. 개인적으로 Stripe의 API 버전 관리 방식을 좋아하는데, 더 알고 싶다면 Stripe의 훌륭한 포스트에서 자세한 내용을 확인할 수 있습니다. AWS는 API를 수 년 간 안정적으로 유지하면서 더 이상 사용하지 말라는(deprecation) 안내 이메일을 보내고 몇 년 동안이나 업그레이드 기간을 제공하기도 했습니다.
- 빠르게 API를 사용할 수 있게 해주세요: 내가 좋아하는 몇몇 API 문서는 몇 초 안에 API 키를 생성하고 API 호출을 시도할 수 있게 해줍니다. 어떤 문서는 심지어 이미 로그인한 상태를 인식하고 내 계정 정보를 기반으로 페이지를 개인화시킵니다. Square가 그 예입니다. 같은 이유로 GraphiQL도 좋아합니다. GraphiQl에서 유저가 그래프 스키마 전체를 볼 수 있고, 요청을 만들고, 변형을 실행하고 코드를 형식화하는 등 다양한 작업을 할 수 있습니다.