프론트엔드 개발자와 문서화: 왜 해야 할까?

왜 문서화가 중요한가?

1. 협업 효율

• 디자이너, 백엔드, QA와의 불필요한 질의/응답 감소

• 예: API 응답 구조, 페이지 라우팅 규칙, 컴포넌트 Props 명세

2. 온보딩 속도

• 신규 팀원이 프로젝트 구조와 규칙을 빠르게 이해하고 기여

3. 유지보수 용이성

• 시간이 지나면 본인 코드의 의도도 흐려집니다. 당시의 설계 이유와 제약이 남아 있으면 문제 원인 파악이 빨라집니다.

4. 품질 보증

• Storybook, 시각 회귀, a11y 체크리스트 등 UI 문서화 도구로 디자인/구현 괴리를 손쉽게 검증할 수 있습니다.

프론트엔드 문서화 유형

1. 라이브러리 CVE 조사 문서화

• CVE ID / 영향 받는 버전 범위 / 현재 사용 버전

• 영향 범위: 런타임/빌드타임, 특정 페이지/국가/브라우저

• 업그레이드 전략: 대체 패키지 여부, 브레이킹 체인지 영향도

• 일정과 담당자: 릴리즈 플랜과 연결

• 관련 ADR 링크: “왜 지금/이 방법으로 처리하는가”의 근거 보존

npm audit fix만으로는 해결되지 않는 경우가 많습니다. 정기적으로 점검하고, 주요 패키지는 별도 트래킹을 권장합니다.

2. ADR(Architecture Decision Record)

• 상태 관리 전환

• 번들러/빌드 체인 변경

• 디자인 시스템/토큰 전략 도입

• 성능/보안/UX에 직결되는 핵심 선택

1. 문제 정의

2. 대안 나열(장단점)

3. 결정 및 근거

4. 파급효과/리스크

5. 후속 작업/롤백 플랜

6. 참조(이슈/PR/릴리즈 링크)

PR/릴리즈에 ADR을 링크해 추적 가능성을 확보

3. 시각 회귀

• 대상 목록: 기준 페이지/컴포넌트, 뷰포트, 테마, 실제 폰트 사용 여부

• 허용 오차: 픽셀/퍼센트 기준

• 무시 영역: 동적 광고/날씨/애니메이션 등

• 베이스라인 승격 정책: 누가/언제/어떤 리뷰로 승격하는가

4. 접근성(a11y)

• 목표 기준: WCAG 2.1 AA

• 자동 점검: eslint-plugin-jsx-a11y, Lighthouse 통과 기준

• 수동 점검: 키보드 순회, 포커스 링 가시성, 스크린리더 레이블, 색 대비

• 토큰 가이드: 대비/폰트/포커스 스타일을 디자인 토큰으로 관리

• DoD에 a11y 체크 포함

문서화 베스트 프랙티스

• Docs-as-code: 문서를 코드와 같은 저장소/브랜치/리뷰 흐름에 포함

• 짧고 명확하게: 1 파일 1 주제

• 자동화 우선: Storybook/OpenAPI/puppeteer

• 변경 동기화: PR 템플릿에 “문서 영향” 체크박스 포함

• 단일 출처 원칙: 산재한 노션/위키는 리드미에서 링크로 수렴

• 소유자 명시: 각 문서/규칙의 Owner와 갱신 주기 표기

마무리