디자인 시스템 문서화 — 쓰는 사람 관점으로

디자인 시스템 문서는 만든 사람의 기록이 아니라 사용하는 사람의 매뉴얼이어야 합니다. 컴포넌트는 잘 만들어놨는데 정작 다른 디자이너나 개발자가 “이거 언제 써야 해요”라고 반복해서 묻는다면, 문제는 컴포넌트가 아니라 문서에 있을 확률이 높습니다.

1. 무엇을, 왜, 언제 — 세 가지만 먼저 채우기

컴포넌트 문서에 프로퍼티 목록만 나열해놓는 경우가 많은데, 사용자가 실제로 궁금한 것은 이 컴포넌트가 무엇인지보다 언제 이걸 쓰고 언제 다른 걸 써야 하는지입니다. 사용 판단 기준을 먼저 적고, 프로퍼티 표는 그다음에 참고 자료로 붙이면 됩니다.

2. 잘못된 사용 예시를 함께 보여주기

올바른 사용법만 보여주는 문서는 절반짜리입니다. 흔히 발생하는 오용 사례를 이미지로 나란히 보여주면, 텍스트 설명보다 훨씬 빠르게 규칙이 전달됩니다.

검색 가능한 구조로 정리하기

디자인 시스템 문서화의 완성도는 얼마나 자세히 썼는지보다 필요한 순간에 얼마나 빨리 찾을 수 있는지로 판가름 납니다. 노션이든 스토리북이든 도구는 크게 중요하지 않지만, 목차 구조와 검색 기능은 반드시 확인해야 합니다.

핸드오프 문서를 잘 만드는 법은 디자인 핸드오프 잘하는 법에서 다뤘습니다.

• 컴포넌트별 사용 판단 기준을 프로퍼티 표보다 앞에 배치하기
• 올바른 예시와 잘못된 예시를 함께 보여주기
• 검색과 목차 구조 확인하기
• 시스템 문서와 핸드오프 문서 역할 분리하기
• 실제 사용자 피드백으로 주기적으로 개정하기

3. 문서에도 담당자가 필요하다

아무리 잘 쓴 문서도 시간이 지나면 실제 컴포넌트와 어긋나기 시작합니다. 컴포넌트의 프로퍼티가 추가되거나 사용 규칙이 바뀌었는데 문서만 예전 버전에 머물러 있으면, 오히려 문서를 안 보느니만 못한 상황이 됩니다. 이 문제를 막으려면 문서에도 명확한 담당자가 있어야 합니다. Shopify의 Polaris나 Atlassian의 디자인 시스템처럼 규모가 큰 시스템일수록 컴포넌트마다 담당자를 지정해두고, 변경 사항이 생기면 담당자가 문서를 함께 업데이트하는 흐름을 릴리즈 프로세스 안에 포함시켜둡니다.

흔히 하는 오해는 문서화를 한 번 몰아서 끝내는 프로젝트로 여기는 것입니다. 실제로는 컴포넌트가 살아있는 한 문서도 함께 갱신되어야 하는 지속적인 작업이며, 이 부담을 특정 담당자 없이 팀 전체의 몫으로 남겨두면 결국 아무도 갱신하지 않는 경우가 많습니다.

버전 이력을 남기는 것도 신뢰를 쌓는 방법입니다. 컴포넌트가 어떤 이유로 언제 바뀌었는지를 간단한 변경 로그로 남겨두면, 사용자는 왜 지금 화면이 예전과 다르게 보이는지 스스로 찾아볼 수 있고, 팀은 과거 결정을 다시 설명해야 하는 반복 질문에서 벗어날 수 있습니다. 변경 로그는 거창한 형식이 필요 없고, 날짜와 변경 내용, 이유 한 줄만 꾸준히 쌓아도 충분합니다.

담당자를 정할 때는 컴포넌트를 처음 만든 사람이 아니라, 지금 그 컴포넌트를 가장 자주 다루는 사람으로 지정하는 편이 현실적입니다. 최초 제작자는 시간이 지나면 다른 업무로 옮겨가지만, 문서는 계속 살아있어야 하기 때문입니다. 담당자가 바뀔 때는 인수인계 항목에 문서 갱신 이력도 함께 포함시켜야 공백 없이 관리가 이어집니다. 담당자 이름을 문서 상단에 명시해두는 작은 습관만으로도, 질문이 필요할 때 누구를 찾아야 할지 헤매는 시간을 줄일 수 있습니다.

4. 마치며

디자인 시스템 문서화는 시스템을 완성한 다음에 하는 부가 작업이 아니라, 시스템이 실제로 쓰이게 만드는 핵심 장치입니다. 만든 사람의 언어가 아니라 찾는 사람의 질문을 기준으로 다시 써보는 것부터 시작하면 됩니다.