[디독] 🍍디자인 시스템 문서 만들기 1편

읽는 디자인 디독

디자인 시스템 문서 만들기 1편

⚡️요약

디자인 시스템 문서화에 대한 글. 디자인 시스템을 작업자들이 보기 편한 형태의 콘텐츠로 가공하는 방법을 이야기합니다. 1)오디언스, 2)전달할 콘텐츠, 3)콘텐츠 분배 구조에 대해 고려해야 할 점들을 개괄적으로 짚어주고 있습니다.

📖 목차

서론
오디언스
콘텐츠
페이지 구조 설계

시스템 오디언스에게 잘 구조화된 콘텐츠 전달하기

#컴포넌트 문서화 7개 시리즈 중 첫 번째 콘텐츠입니다.

Intro / Examples / Design / Code / Authoring / Myths

고퀄리티 컴포넌트 문서는 효율적인 라이브러리를 만들어준다. 우리는 효율적인 디자인 의사 결정과 빠른 개발에 초점을 맞추어, UI 컴포넌트들을 엄격하게 정의한다. 좋은 문서는 공짜로 얻을 수 없다. 차별점을 지니기 위해서는 좋은 사례와 가이드라인을 만드는 계획, 노력 그리고 과정을 들여야 한다.

이제부터, 이 6개의 아티클 컬렉션은 컴포넌트 문서화에 대한 이야기를 전반적으로 훑어볼 것이다. 오디언스, 콘텐츠, 그리고 구조 전략부터 시작하고자 한다. 그 다음에는, 아티클마다 소개, 사례, 디자인/코드 가이드 그리고 과정을 포함한 결론에 대해 다룰 예정이다. 내가 몇 년 간 익혀오고, 요즘까지도 커뮤니티에서 공유하며 얻고 있는 영감들을 습득할 수 있는 팁들을 제공할 것이다.

먼저, 질문으로 이 글을 시작해보자. : 이 문서의 오디언스는 누구이며, 그들이 원하는 콘텐츠는 무엇이며, 그것을 전달하기 위해 어떻게 해야 페이지를 최적으로 구조화할 수 있을까?

1. 오디언스

가장 먼저 고려해야 할 것 : 누구를 위한 것인가? 이에 대한 대답은 보통 하나가 아닐텐데, 어느 쪽이 더 중요한가?

1) 엔지니어, 디자이너, 그리고 모든 사람들!

라이브러리가 코드를 제공한다면, 오디언스는 당연히 엔지니어이다. 라이브러리가 코드로만 구성되어있다면, 그 문서가 디자이너에게 제공되어야 할 필요가 있을까? 문서에 코드 없이 디자인 가이드만 있다면(예: 구글 머터리얼), 엔지니어가 볼 필요가 있을까?

물론 두 경우 모두 틀린 답은 아니다. 컴포넌트 문서는 항상 두 오디언스 모두를, 다양한 각도에서 고려해야 한다.

하지만 그 외에, 또 누가 있을까? 특히 시스템이 곧 팀이 일하는 방식으로 이어지는 경우에 말이다. 파워풀하고, 간결한 인트로는 PM을 감동하게 만든다. 사례는 QA 전문가들에게 적절한 상태를 노출한다. 스타일, 패턴(behavior), 편집 문제는 리서처와 콘텐츠 전략가 같은 사람에게 방향을 제시한다. 사용성 전문가는 그들이 해오던 일을 하는 거고.

많은 시스템 팀은 그들이 만든 시스템을 외부에 공개적으로 보이도록 배포하기도 한다. 본질적으로는 공유를 위함이지만, 추가적으로는 사이트를 채용 수단으로 사용하기 위함도 있다. 시스템은 높은 퀄리티, 기술력과 협업력, 잘 정리된 사례들을 보여주어, 재능 있는 신입 사원이 회사에서 강점을 볼 수 있도록 만들어야 한다.

문서의 가장 중요한 목적은 이것이다. : 전문가들ㅡ엔지니어, 디자이너, 관련된 모든 사람들ㅡ이 시스템을 효과적이고 효율적으로 사용할 수 있도록 무장시키는 것. 시스템이 성장할수록, 다양한 니즈와 잦은 사용 빈도에도 불구하고 많은 것들을 제공할 수 있다.

2) 엔지니어, 그 다음 디자이너, 그 다음 나머지 사람들

모든 사람에게 제공한다는 게 모두 똑같이 제공한다는 뜻은 아니다. 엔지니어는 하루에 문서를 5번, 10번, 혹은 그 이상 들여다본다. 코드 에디터 옆에 항상 띄워져있을 수도 있다! 디자이너는 이것저것 비교하면서 가끔 세부사항을 반영하기 때문에, 그보다는 좀 더 적게 방문할 것이다. 콘텐츠 전략가나 리서처는 의사 결정 할 때에만 아주 가끔씩 방문할 것이다.

자, 그럼 누가 가장 중요할까? 내 경험상으로 시작점은 매우 분명하다. : 시스템은 엔지니어와 디자이너의, 에 의해, 를 위해 만들어져야 한다. 물론 다른 사람들도 오디언스 중 하나가 될 수 있으며, 이점을 얻겠지만 디자이너와 엔지니어에 비해서는 덜 중요하다. 부차적인 오디언스를 챙기는 것은 어쩌면 트레이드 오프와도 같다. 엔지니어와 디자이너를 중요하게 생각하지 않는 건 문제다. 진짜 큰 문제.

엔지니어 VS 디자이너는 어떨까? 내가 작업했던 모든 시스템은 디자인과 코드 모두를 제공했다. 내가 다른 조직에서 봤던 몇몇 문서는 각각에게 강하게 편중되어있거나, 따로 노는 목적성을 띄고 있었다(이 부분은 다음에 더 얘기하기로). 시스템을 만들 때에는 많은 관점에서 고려해야 한다. : 만드는 목적, 사용 빈도, 콘텐츠 뎁스, 퀄리티, 콘텐츠 생산 비용, 업무 연관도 같은 것들.

나는 디자이너다. 동시에 프로그래머이기도 하다. 아무 맥락 없는 상태에서 둘 중에 하나를 고르라면, 엔지니어쪽을 선호하는 편이다. 이미 코드로 구현된 의사 결정을 두꺼운 가이드북으로 읽고 있는 50명의 디자이너보다 잘 디자인된 컴포넌트를 코딩하는 엔지니어 50명을 구하는 것이 경험을 효과적으로 빌딩할 확률이 높기 때문.

노트: 오디언스 우선순위는 다양한 요소들에 따라 달라진다. 디자이너와 엔지니어가 충돌할 것이라는 걸 예상하고, 그 둘을 최적화하기 위한 시도를 해야 한다. 그럴 수 없다면, 최종 결과물에 좀 더 가까운 수단을 사용하는 사람들을 위한 결정을 내려야 하며, 이는 대부분 코드다. 즉, 엔지니어가 먼저고 디자이너는 그 다음이라는 것.

2. 콘텐츠

컴포넌트 문서는 당신이 제공할 수 있는 콘텐츠와 오디언스를 연결해준다. 콘텐츠는 다양한 형태를 갖추고 있고, 모두 같은 비용이 드는 것은 아니며 그것들을 한 데 엮는 것도 당신에게 달려있다.

크게 보면, 컴포넌트 문서는 보통 다음 네 가지 유형을 포함하고 있다.

소개: 컴포넌트의 이름과 해당 요소의 톤을 설정하는 간단한 설명. (필수)
사례: 컴포넌트의 베리에이션, 상태 및 기타 수치를 나타내며, 정적인 이미지보다는 코드와 결합하여 표시하는 것이 좋다.
디자인 레퍼런스: 언제 사용하는지와 Do&Don't, 비주얼, 인터랙션, 카피에 대한 가이드라인. (권장)
코드 레퍼런스: 디테일한 코드 API(Props같은)와 다른 보충 설명. (코드 있을 시 필수)

1) 종류에 따른 콘텐츠 제작 비용 변화

각각에 드는 비용은 천차만별이다. 소개는 빠르고 가벼워야 하며, 한 두 문장을 쓰는 것으로 사례를 대신한다. 잘 구성된 사례는 시간이 지나면서 예측 가능하도록 만들기 위해서 필수적인 투자다. 코드 레퍼런스는 엔지니어들이 단순 빈칸 채우기를 해야 하는 지루한 템플릿이 있을 경우에는 직관적으로 드러나야 한다.

잠깐, 숨을 크게 들이쉬자. 효율적인 디자인 레퍼런스는 매우 비용이 많이 들거나, 기본 사항만 작성하거나, 아예 생략할 수도 있다. 디자인 내러티브는 시스템의 목적과 팀의 케파와 역량, 커뮤니티의 필요에 달려있다.

노트: 컴포넌트 문서는 넓은 범위의 콘텐츠를 포함한다. 그러니 팀의 가치를 상기하기 위해 상단에서부터 논의를 시작하고, 디자이너와 엔지니어가 구분되는(코드 VS 디자인 레퍼런스), 겹쳐지는(인트로), 혹은 공유할 수 있는(네이밍과 콘텐츠, 순서 등의 사례) authoring 유형에 대해 논의하자.

3. 페이지 구조 설계

1) 디자인&코드: 분절하기 위함인가, 결합하기 위함인가?

실제로, 컴포넌트 문서는 의도적인 선택 및 어쩔 수 없는 제약 모두에게서 나올 수 있다. 종종, 컴포넌트 문서는 분절된 콘텐츠로 귀결되곤 한다.: 디자이너는 디자이너를 위해 발행하고, 엔지니어는 엔지니어를 위해 발행하는 식으로... 이러한 분절은 양측 모두에 사고를 일으킬 수 있다. 그러므로, 컴포넌트 페이지의 IA를 초반에 논의해야 한다.

구글 머터리얼의 문서는 분절되어있다. 머터리얼의 디자인 파운데이션은 Material Design Lite와 Polymer Project부터 안드로이드 개발자의 디자인 섹션과 Meterial UI(리액트를 위해 설계된)가 구현되기 전에 생겨났다. 이러한 구현 사례는 그들의 디자인 상위 개념과 느슨하게 연결되어있으며, 코드에 지장을 주지 않는 선에서만 유지되고 있다.

Google Material은 Material Design, Material Design Lite, Material UI의 데모와 API에 걸쳐 그들의 스토리를 뿌리고 있다.

이러한 분절은 필수적일 뿐만 아니라, 의미있고 정당한 방식이기도 하다. 솔직히 Material이 뿌려놓은 프레임워크, 팀, 플랫폼은 현존하는 다른 어떤 디자인 시스템보다 우수하다. 하지만 주의: 우리는 Google Material이 되는 것을 목표로 하는 게 아니다!

나머지 사람들에게는, 디자인은 여기에 있고, 엔지니어링은 저기에 있는 식이 일반적이다. 이러한 방식는 각각의 오디언스의 리딩 경험을 별도로 최적화하면서, 일관적인 규칙을 통해 내용에 집중시킨다.

컴포넌트 디자인 가이드와 코드&API 문서는 별도의 사이트를 통해 느슨하게 짝지어져있다. 사례: Atlassian

디자인/코드를 분리하는 것은 리스크를 가져오기도 한다. 시간이 지나면, 사이트는 다음과 같은 문제에 빠지게 된다.

분류 체계 분리(loader&spinner같은 아주 간단한 이름조차도)
피쳐 분리: 디자인이 코드에서 구현할 수 없는 딥한 피쳐까지 표현하거나, 코드가 디자인되지 않은 결과물을 만들어내거나.

서로 합의되지 않았다는 느낌 정도는 괜찮다. 스토리라인도 별개고. 뭐, 적어도 각각의 작업자들의 워크플로우에는 일관적으로 제공되고 있으니까.

하지만 이것들을 실제로 적용해야 하는 adopter들은 하나로 통일된 소스를 원한다. 두 가지 모두에 역할이 분배되어있는 사람들은 테니스 공처럼 앞뒤로 왔다갔다한다. 마치 adopter들이 알아서 짜맞춰야 하는 것처럼, 뚜렷하게 설계된 유용한 디테일들이 양측 모두에 존재한다.

노트: 디자인과 코드를 나눌 때는 주의하자. 처음에는 author들에게, 또 퍼블리싱하기에 편할지 몰라도, 시간이 지나면 그러한 이익을 넘어서는 리스크가 발생할 수 있다. 쌍둥이 사이트를 만드는 것은 디자인과 엔지니어링 간의 거리감을 확연하게 드러낼 수도 있다.

2) 스레드 콘텐츠인가, 스택 혹은 탭인가?

Morningstar Design System같은 내가 몇 년간 리드해온 많은 시스템에서는 디자인과 코드를 함께 스레드하여 제공해왔다. adopter들은 통일된 이름과 가이드, 베리에이션과 피쳐를 어떻게 사용해야 하는지에 대한 내러티브를 찾아볼 수 있다.

디자인과 코드 콘텐츠를 한 스크롤 내에서 함께 열람할 수 있게 만든 컴포넌트 문서 페이지.(Morningstar Design System)

스레드 형식으로 구성된 페이지는 다음과 같은 리스크를 지니고 있다.: 관련된 다양한 콘텐츠를 제공함으로써 스크롤이 훨씬 길어진다. 대안으로써, 다른 시스템은 탭 형태의 소개를 제공하기도 한다.

노트: 디자인과 코드를 한 데 두는 것은 가능하며, 팀은 그들의 용도에 맞는 UI를(스택, 탭, 그 외 다른 것들) 선택하기만 하면 된다.

3) 콘텐츠를 타입별로 그룹핑하고 나열하기

스택이든 탭이든, 나는 일관적인 콘텐츠 우선 순위와 나열 순서를 중요시하게 되었다.

(1) 소개

(2) 사례: 가장 중요하게 생각하는 ㅡ전면, 그리고 중앙에 내놓고 싶은 이상적인 컴포넌트

(3) 디자인 가이드는 사례로 덧붙여 설명할 수 있지만, 콘텐츠가 지나치게 길어질 수 있다.

(4) 코드 레퍼런스는 예측 가능하게 설계되고 믿을만하게 적용된다. 엔지니어가 팀 내에서 가장 중요하고 우선권을 지니고 있다면, 이 레퍼런스를 중요한 위치에 배치해야 한다.

사례 규칙, 그리고 딥한 디자인과 코드 레퍼런스는 클릭 한 번 정도의 길이라면 괜찮을 것이다. 흥미롭게도, 업계의 사례들은 일관성 없는 라벨과 다양한 순서로 디자인 및 코드의 이름을 지정하고 우선 순위를 정한다.

분리된 콘텐츠는 어떤 콘텐츠가 우선 순위인지 표기할 수 있다.: (예를 들면) 코드 먼저, 디자인 먼저, 혹은 위 사례처럼 모두 한 탭에 몰아두거나.

IBM Carbon은 코드를 가장 중요시하고 디자인 디테일을 용법이나 스타일 같은 추가적인 탭에 남겨둔다. Hudl's Uniform 시스템은 우선 순위를 바꾸어, 디자인을 코드 앞에 두고 비슷하지만 똑같지는 않은 내용 분류 방식을 가진 두 번째 탭으로 내렸다.

Salesforce의 Lightning Design System은 개발자 가이드라인 탭을 기본으로 하고, 그 위에 컴포넌트를 탐색할 용도로 감각적인 사례들을 제시하지만, 구현 노트와 디자인 가이드라인 탭은 이상하리만치 비워두었다.

조직에 따라, 디자인 탭 전후에 추가적인 섹션(주로 접근성)도 함께 나타나기도 한다.

노트: 소개로 시작하여 사례를 눈에 띄는 자리에 배치하자. 그 외에도, 디자인과 코드 가이드의 우선 순위는 조직과 그들이 오디언스와 스토리텔링에 두는 가치에 따라 달라진다.

4) 페이지가 길어질 때는, 지속적으로 붙어있는 로컬 네비게이션을 활용한 앵커 리더.

페이지가 길어질수록, 이 페이지가 무엇인지, 그리고 현 위치가 어디인지 짚어주는 것이 더 중요해진다. 이럴 때는, 세로형 로컬 네이게이션이 효과적이다.: 항상 떠있고, 스크롤 시 위치 추적이 가능하고, 도중에 서브 타이틀로 이동 가능한 네비게이션.

Morningstar Design System은 페이지의 오른쪽 영역을 따라 두 단계의 위계를 사용해 로컬 네비게이션을 구성했다.

노트: 많은 사이트 트렌드가 붙어있는 버티컬 네비게이션을 사용하긴하지만, UI(탭이나 단일 스크롤 뷰)는 취향에 따라 선택할 수 있다. 오디언스에게 질문하고, 콘텐츠를 이해하고, 사용성을 극대화하고, 무슨 일이 있어도 섹션명과 컴포넌트명을 라이브러리 전반에 걸쳐 일관되게 유지하자.

5) 디자인? 코드? 둘 다?

디자인과 코드 스레드가 더 많을수록, 좀 더 관심이 많은 오디언스들은 그들의 용도에 맞게 페이지의 인터페이스를 다듬어 달라고 요청할 것이다.

디자인 매니저: 코드 샘플과 레퍼런스 테이블을 안 보이게 할 수는 없나요?

엔지니어: 이 길다란 디자인 스토리텔링 좀 없애버릴 수 없나요?

디자인이나 코드 콘텐츠를 숨길 수 있는 토글을 고려해보는 것도 좋다. 이를 위해서는 각 콘텐츠 유형을 하나에만 해당하는 것, 다른 하나에 해당하는 것 혹은 둘 모두와 관련된 것으로 분류해야 한다.

항상 표시되는 소개, 사례, 접근성과 관련된 모든 요소들.
"디자인만" 원한다면 코드 정보와 Prop나 CSS Modifier Calsses같은 테크니컬한 가이드를 숨길 수 있다.
"코드만" 원한다면 비주얼 스타일에 관한 기다란 섹션과 편집(카피)에 대한 내용을 숨길 수 있다. 하지만 엔지니어와도 관련된 몇몇 기본 가이드 ㅡ특히, 언제 사용하는지ㅡ는 남겨두어야 한다.

비슷한 맥락에서, Hudl's Uniform은 페이지 내에서 디자인과 코드를 구분할 수 있는 토글과, 유저 지향적인 탭을 제공했다

Hudl's Uniform 디자인 시스템은 페이지 단위의 토글(우상단)을 통해 디자인과 코드 가이드를 구분했다.

이러한 방식은 구현은 원활하지만 UI 구축과 콘텐츠의 효율적인 관리라는 비용이 요구된다. 내가 겪은 다른 클라이언트들도 디자인과 엔지니어링을 구분하는 동시에 개방된 경계를 인정하면서 비슷한 한계에 부닥치곤 했다.

노트: 콘텐츠 타입 기반 필터링은 기술적인 것보다 콘텐츠 매니징에 대한 비용을 들이게 된다. IA가 엄격할수록, 기회는 더 많아지겠지만 이는 효과적인 authoring 워크 플로우와 과업의 분리에 따라 달라진다.

오디언스에 대한 강한 감각을 지니고, 제작된 콘텐츠의 종류를 이해하며, 큰 범위의 페이지 구조를 합의했다면, 이제 작업을 시작해보자.

다음 글 → #2 소개

저자 : Nathan Curtis

원문 링크: https://medium.com/eightshapes-llc/documenting-components-9fe59b80c015

번역자 : 김강령

👀 강령's 큐레이팅 멘트

디자인 시스템 문서 작업에 관한 시리즈 중 첫 번째 아티클입니다. 미디엄에서 디자인 시스템 관련 글로 유명한 Nathan cutis님의 글인데요. Morningstar Design System을 구축하신 분이라고 하네요.

author들이 쉽게 이해할 수 있도록 문서화하는 것도 디자인 시스템을 구축하는 것만큼 중요한 일인데요. 이러한 문서화를 할 때 고려해야 할 점들을 잘 짚어주고 있습니다.

오늘 콘텐츠는 어떠셨나요?

유익했어요 😍 | 보통이에요 😶 | 아쉬워요 😔

같이 읽고 싶은 친구가 떠오른다면

👉구독링크 공유하기

http://bit.ly/2FNQNpv

번역이 필요한 아티클이 있다면

👉 디독에게 알려주기

[디독 도네이션 OPEN]

작은 금액이라도 디독의 서비스 유지를 위해 후원해주시면 감사하겠습니다. :)

카카오뱅크 3333 14 0517 920 (심예지)

*후원해주신 금액은 전액 서비스 운영(메일 발송 솔루션 비용)에 사용됩니다.
*후원자(입금자명) 리스트 기입을 원하지 않으시는 분은 메일로 말씀해주세요.

4월 후원해주신 분들

주현정, 이혜빈, 김수현, 황하나, 서은정, 박지윤, 박재덕, 허사랑, 정찬우 외 2분

후원해주신 분들, 정말 감사합니다! 덕분에 서비스를 유지할 수 있게 되었습니다. :)

디독
d.dok.newsletter@gmail.com
-
수신거부 Unsubscribe

좋은 뉴스레터를 만들고 전하는 일,
스티비가 함께 합니다