때때로 유능한 소프트웨어 개발자로서 나는 좋은 문서를 좋아합니다 . 이는 사물이 어떻게 작동하는지뿐만 아니라 왜 그런 방식으로 작동하는지 설명합니다. 최선의 경우 문서는 가이드 이상의 역할을 합니다. 이는 사람들이 이해하고 믿는 데 필요한 정보를 제공하는 원칙과 모범 사례에 대한 설명입니다. 소프트 스킬이 기술 분야에 진출함에 따라 문서 유지 관리가 바로 그 자리에 있습니다. Smashing은 이전에 제안 컨텍스트에서 디자인 문서를 탐색했습니다 . 그러나 일단 답변에 도달하고 구현해야 하는 경우에는 어떻게 될까요? 무언가를 연구하고 구축해야 하는 사람들에게 유용한 방식으로 정보를 어떻게 제공합니까? 문서에는 기술적인 측면이 있는 경우가 많지만, 이 문서에서는 문서를 디지털 디자인, 특히 웹 디자인에 어떻게 적용할 수 있는지에 대해 설명합니다. 아이디어는 아름답고 유용한 디자인 문서, 즉 가이드이자 선언문을 동시에 만들기 위해 두 세계의 장점을 최대한 활용하는 것입니다. 문서에 대한 찬사 # 살아 숨 쉬는 디지털 디자인 문서에 대해 자세히 알아보기 전에 문서가 무엇인지, 문서의 용도는 무엇인지, 문서가 왜 그렇게 가치 있는지 잠시 다시 살펴보는 것이 좋습니다. 문서에는 제품, 시스템 또는 서비스가 작동하는 방식, 용도, 현재 방식으로 구축된 이유, 이미 진부한 정신과의 연결을 잃지 않고 작업할 수 있는 방법이 설명되어 있습니다. 우리는 코드 문서의 핵심을 다루지는 않을 것입니다. 그 가려움증을 긁어줄 스매싱 기사가 많이 있습니다: “ Figma에서 더 나은 디자인 핸드오프 파일 디자인하기 ”, Ben Shih “ 간소화된 코드 문서화 ,” Atila Fassina " 개발자를 위한 문서화 작업 흐름을 자동화하는 방법 " Portia Burton “ 제품 디자인 문서를 통한 문서화 및 팀 커뮤니케이션 개선 ,” Ismael González 그러나 문서화의 몇 가지 주요 이점을 간략하게 설명하겠습니다. 기술 부채 감소 # 우리의 결정은 스스로를 표현하지 않는 코드 주석보다 더 공식적인 것으로 기록하고 정당화해야 할 때 훨씬 더 확고해지는 경향이 있습니다. 명확하고 읽기 쉬운 코드를 갖는 것은 항상 노력할 가치가 있지만 지원 문서는 필수적인 컨텍스트와 지침을 제공할 수 있습니다. 연속성 # 우리는 이직률이 유난히 높은 업계에 종사하고 있습니다 . 누군가의 머리 속에 살고 있는 풍부한 지식은 그들이 떠날 때 함께 사라집니다. 누군가가 나아갈 때마다 바퀴를 재발명하고 싶지 않다면 문서를 사랑하는 법을 배우는 것이 좋습니다. 바로 여기에 연속성이 있습니다. 불필요한 반복 방지 # 때때로 상황은 매우 타당한 이유로 현재의 방식으로 유지되며, 어딘가에 있는 누군가는 그것이 무엇인지 이해하기 위해 많은 고통을 겪어야 했습니다. 그렇다고 특정 결정의 근거가 면밀히 조사할 필요가 없다는 말은 아닙니다. 문서는 그것을 가장 중요한 위치에 놓는다. 설득력 있고 훌륭하다면 사람들은 자신감을 가지고 계속 나아갈 수 있습니다. 더 이상 유지되지 않으면 옵션을 재평가하고 코스를 신속하게 변경할 수 있습니다. 문서화는 일련의 규범을 확립하고, 불필요한 반복을 방지하며, 더 빠른 문제 해결을 가능하게 하고, 이상적으로는 영감을 줍니다. 모바일 인터페이스용 터치 디자인을 만나보세요 . 입증되고 보편적이며 인간 중심적인 지침을 갖춘 Steven Hoober의 새로운 모바일 디자인 가이드입니다. 400페이지 , 심층적인 사용자 조사 및 모범 사례 로 가득 차 있습니다 . 목차로 이동 ↬ 기능 패널 두 개의 세계 # 1959년 영국 작가 CP Snow는 “ The Two Cultures ”(PDF) 라는 제목의 세미나를 진행했습니다 . 전체적으로 읽어볼 가치가 있지만 요점은 과학과 인문학이 함께 작동하지 않으며 인류가 번영하려면 실제로 그렇게 해야 한다는 것입니다. 전문화로 우리 자신을 제한하는 것은 각 그룹의 지식을 박탈하는 것입니다. “양극화는 우리 모두에게 엄청난 손실입니다. 사람으로서 우리와 사회에. 이는 실용적이면서도 지적이고 창의적인 손실입니다. [...] 이 세 가지 고려 사항이 명확하게 분리될 수 있다고 상상하는 것은 거짓입니다.” — 찰스 퍼시 스노우 Snow 자신도 "어떤 것을 둘로 나누려는 시도는 많은 의심을 받아야 한다"고 인정했지만, 프레임은 유용했고 여전히 유용합니다. 웹 개발은 디자이너와 엔지니어, 예술과 데이터 사이의 세계의 만남이며, 그들이 만나는 장소는 실제로 좋은 일이 일어나는 곳입니다. “두 주제, 두 분야, 두 문화, 즉 두 은하계의 충돌 지점이 창의적인 기회를 만들어내야 합니다.” — 찰스 퍼시 스노우 스노우도 알고 있었고, 레오나르도 다빈치도 알고 있었고 , 스티브 잡스도 알고 있었습니다. 우리가 충돌을 향해 직진할 때 마법이 일어납니다. 공통 언어 # 웹 개발은 서로 다르지만 연결된 전문 분야(그리고 해당 분야의 하위 전문 분야)로 이루어진 세계입니다. 핵심 관계 중 하나는 엔지니어와 디자이너 간의 관계입니다. 두 가지가 조화를 이루면 놀라운 결과가 나올 수 있습니다. 그렇지 않으면 관련된 모든 사람과 모든 사람이 고통을 겪습니다. 디지털 디자인에는 예술, 기술, 상호작용성, 반응성의 혼합이라는 고유한 언어가 필요합니다. 문서는 살아 있기 위해 가지고 놀 수 있는 것을 반영해야 합니다. 누군가가 단어를 읽기 전에 이야기를 시작해야 합니다. 그렇게 하면 작가, 개발자, 디자이너, 커뮤니케이터 등 참여하는 모든 사람이 더 나은 결과를 얻을 수 있습니다. 디자인 문서는 두 세계의 요소로 구성된 공통 언어인 세계 사이의 다리를 만듭니다. 디자인과 엔지니어링은 점점 더 밀접하게 얽혀 있습니다. 문서가 이를 반영하는 것이 옳습니다. 웨비나: Angular v17의 비밀과 놀라움에 대해 더 자세히 알아보세요! 자리를 비워두세요 설계 문서 # 그래서 여기 있습니다. 디자인 문서의 핵심입니다. 우리는 몇 가지 주요 고려 사항과 유용한 리소스 및 도구를 다룰 것입니다. 디자인 문서, 기술 문서, 디자인 시스템의 차이가 항상 명확하지는 않지만 그래도 괜찮습니다. 상황이 조금 흐릿해지기 시작하면 목표는 시각적 아이덴티티를 확립하고, 그 뒤에 숨은 원칙을 설명하고, 이를 최대한 원활하게 구현하는 데 필요한 리소스를 제공하는 것임을 기억하세요. 무엇을 다루어야 하는지는 이 글의 요점이 아니라 어떻게 다루어야 하는지에 대한 것입니다. 하지만 시작하려면 아래에 나열된 내용을 참조하세요. 설계 원칙 타이포그래피 구성 요소 라이브러리 삽화 사진술 도상학 색상 브랜딩 접근성 소리 디자인 문서화의 임무는 이러한 모든 것(그리고 그 이상)을 함께 엮는 것입니다. 방법은 다음과 같습니다. 이유를 공유하세요 # 디자인 시스템과 문서를 생각할 때 글꼴, 색상, 구성 요소 등으로 넘어가는 것은 이해할 수 있지만 해당 자산에 도달하는 데 도움이 된 정신을 공유하는 것도 중요합니다. 이 모든 것이 어디서 왔습니까? 비전은 무엇입니까? 기본 원칙은 무엇입니까? BBC는 공유 디자인 프레임워크인 GEL(Global Experience Language) 에 대해 이러한 질문에 답하는 데 능숙합니다 . 대중에게 공개되는 것 외에도(나중에 자세히 설명) 지침과 디자인 패턴에는 전체 시스템의 기본 원칙을 설명하는 기사와 플레이북이 함께 제공됩니다. 메뉴에 지침, 기사 및 플레이북이 포함된 Global Experience Language 웹사이트의 스크린샷 ( 큰 미리보기 ) 제안서가 있는 경우 업무 관행뿐만 아니라 제안서도 포함하세요. 디자인이 누구를 위해 만들어졌는지 명확히 하세요. 거의 모든 시스템에는 대상 고객을 염두에 두고 있으며 이를 최우선으로 삼아야 합니다. 기본 원칙을 삭제하는 것은 미국 역사 강의 계획서에서 헌법을 제외하는 것과 같습니다. 창조를 협업 프로세스로 만드세요 # 디자인 시스템은 큰 텐트입니다. 어쨌든 디자인, 엔지니어링, 카피라이팅, 접근성, 심지어 법적 고려 사항까지 최선을 다해 통합합니다. 이러한 모든 세계에는 문서에 대한 입력이 있어야 합니다. 회사/프로젝트가 클수록 여러 팀이 의견을 제시해야 할 가능성이 높아집니다. 문서가 공동 작업 방식으로 작성되지 않은 경우 구현이 다를 것으로 예상해야 하는 이유는 무엇입니까? “ 동적 플랫폼 사용 # 책에 인쇄된 브랜드 지침만으로 충분했던 시대는 이미 지났습니다. 현대 생활의 대부분이 온라인으로 전환되었으므로 문서화에 대한 지침도 마찬가지입니다. 다행스럽게도(혹은 벅차게도) 세상에는 수많은 플랫폼이 있으며, 그 중 다수는 서로 완벽하게 통합되어 있습니다. 잠재적인 리소스/플랫폼은 다음과 같습니다: 스토리북 피그마 구성 요소 라이브러리 GitHub 위키 제플린 스케치 인비전 세계 간의 연결을 촉진하는 플랫폼 체인이 있을 수 있습니다. Figma는 Storybook으로 이어질 수 있고, Storybook은 프로젝트에 직접 통합될 수 있습니다. 디자인 문서를 기술 생태계로 받아들입니다. 디자인 문서를 코드 베이스 자체와 통합하여 민첩하고 지속적인 개발을 수용합니다. 사용 사례를 염두에 두고 작성 # 디자인 문서의 추상적이고 철학적인 측면이 중요하기는 하지만, 그것이 설명하는 시스템은 궁극적으로 사용되기 위한 것입니다. 사용자의 목표를 고려하십시오. 디자인의 경우 모범 사례와 일치하는 것을 구축하는 것입니다. 독자들에게 디자인 지침을 사용하는 방법을 보여줍니다 . 출력을 명확하고 실용적으로 만드십시오. 예를 들어, 디자인 시스템 글꼴을 사용하여 React 구성 요소를 만드는 방법 팔레트에서 적절한 색상을 선택하는 방법. 앞서 살펴본 것처럼 디자인은 명확하고 인식 가능한 섹션(타이포그래피, 색상 등)으로 나뉩니다. 이러한 섹션은 여러 단계로 나눌 수 있으며, 후자의 섹션은 명확하게 실행 가능합니다. 기능은 무엇입니까? 문서화를 가장 유용하게 만드는 데 필요한 지식 기능 사용 사례 구현; 제안된 도구. Mailchimp 패턴 라이브러리는 실제로 이에 대한 좋은 예입니다. 사용 사례는 문서에 바로 통합되어 있으며 상황에 맞는 참고 사항과 예제 코드 조각이 포함되어 있어 모범 사례를 명확하고 쉽게 구현할 수 있습니다. Mailchimp 패턴 라이브러리의 스크린샷 ( 큰 미리보기 ) Carolyn Stranksy 의 강연인 문서 인간화(Humanising Your Documentation)는 사용자를 위한 문서 작업에 대한 놀라운 개요를 제공합니다. 문서는 사물이 어떻게 작동하는지 설명하기보다는 사람들이 목표를 달성하는 데 도움이 되어야 합니다. “ StackOverflow 창립자 Jeff Atwood가 한때 말했듯이, "잘 설계된 시스템은 올바른 일을 하기 쉽게 하고, 잘못된 일을 하기는 짜증나게 합니다(그러나 불가능하지는 않습니다)." Tyner Blain의 " Use Case Driven Documentation " 은 Vitaly Friedman의 " On Design Systems: Sell The Output, Not The Workflow " 와 마찬가지로 이러한 정신을 훌륭하게 분석한 것입니다 . 언어 # 말하는 방식이 중요합니다. 문서는 명확하고, 접근 가능하며 수용 가능해야 합니다. 거의 모든 문서와 마찬가지로 '그냥', '단순히', '단순히'와 같은 단어를 폭넓게 사용하세요. 한 사람에게는 단순한 것이 다른 사람에게는 항상 그렇지는 않습니다. 문서는 정보를 제공해야 하며, 경시해서는 안 됩니다. Write the Docs의 " 글쓰기의 편견 줄이기 "는 여기서 훌륭한 지침을 제공합니다. 명심해야 할 또 다른 사항은 사용하는 언어입니다. "그" 또는 "그녀"를 사용하는 대신 "하나", "그들", "개발자" 등을 사용하세요. 누군가에게는 큰 문제가 아닌 것처럼 보일 수도 있지만(내가 거기서 무엇을 했는지 확인하세요), 그러한 언어는 귀하의 리소스가 모든 사람을 위한 것임을 강화하는 데 도움이 됩니다. 보다 일반적으로는 사본을 명확하고 요점을 명확하게 유지하십시오. 말처럼 쉽지는 않지만, 글을 정리하는 데 도움이 되는 도구가 많이 있습니다. 무감각하고 배려심 없는 글을 잡아내는 도구인 알렉스(Alex) ; Write Good , 영어 산문 린터입니다. 이전 Smashing 기사 " 가독성 알고리즘은 대상이 아니라 도구여야 합니다 "에서 저는 Grammarly 나 Hemingway Editor 와 같은 도구가 작성 방법을 지시하지만 유용한 도구라는 점에 대해 경계심을 공유했습니다. 또한 나는 조지 오웰(George Orwell)의 언어 규칙을 공유하는 좋은 변명을 결코 거부할 수 없습니다 . 인쇄물에서 흔히 볼 수 있는 은유, 직유 또는 기타 비유적 표현을 절대 사용하지 마십시오. 짧은 단어가 사용되는 곳에 긴 단어를 사용하지 마십시오. 단어를 잘라내는 것이 가능하다면 항상 잘라내십시오. 능동태를 ​​사용할 수 있는 곳에 수동태를 사용하지 마십시오. 일상적인 영어로 상응하는 단어가 생각나면 외국어, 과학 단어, 전문 용어를 사용하지 마세요. 노골적으로 야만적인 말을 하기보다는 빨리 이러한 규칙을 어기십시오. William Strunk Jr의 The Elements of Style (PDF) 과 같은 책 도 알아두면 좋습니다. 정보를 제공하되 간결하게 유지하세요. 스매싱 매거진으로 광고하기 아름답게 만들어 보세요 # 디자인 문서는 걸어가는 것이라면 훨씬 더 신뢰성이 높습니다. 만약 그것이 엉망진창처럼 보인다면, 그것이 심각하게 받아들여질 가능성은 얼마나 됩니까? 이상적으로는 단순히 설명하는 것이 아니라 디자인 정신을 보여주어야 합니다. NASA는 1976년에 매뉴얼 자체가 아름다울 수 있다는 것을 보여주었습니다(PDF). Richard Danne과 Bruce Blackburn이 쓴 그래픽 표준 매뉴얼은 그 자체로 창의적인 작품처럼 느껴집니다. 그래픽 표준 매뉴얼의 디자인 이미지 출처: 표준 매뉴얼 . ( 큰 미리보기 ) 그래픽 표준 매뉴얼의 디자인 이미지 출처: 표준 매뉴얼 . ( 큰 미리보기 ) 그래픽 표준 매뉴얼의 디자인 이미지 출처: 표준 매뉴얼 . ( 큰 미리보기 ) 사용자가 디자인 문서를 적용할 때 보여주기를 기대하는 디자인 문서의 세부 사항에 동일한 주의와 주의를 기울이십시오. 문서는 실제로 실행되는 최초이자 최고의 예가 되어야 합니다. 문서를 쉽게 탐색하고 검색할 수 있도록 만드세요. 세상에서 가장 훌륭한 자원도 찾을 수 없다면 누구에게도 큰 도움이 되지 않습니다. 또한 정보 아키텍처 모범 사례를 실제 사례로 보여줄 수 있는 훌륭한 기회이기도 합니다 . 게시 # 디자인 시스템을 만들고 그것이 어떻게 작동하는지 설명하는 수고를 겪은 후에 왜 그것을 혼자서만 간직하고 있습니까? 문서를 게시하고 누구나 무료로 검색할 수 있도록 하는 것은 환상적인 최종 마무리입니다. 예를 들어 Guardian 에서는 소스 디자인 시스템인 Storybook을 누구나 볼 수 있으며 해당 코드는 GitHub에서 공개적으로 사용할 수 있습니다 . 시스템 자체의 시험장이 될 뿐만 아니라, 지식 공유를 위한 공간을 창출합니다. 다음은 공개적으로 사용 가능한 설계 문서의 몇 가지 환상적인 예입니다. Google의 머티리얼 디자인 GOV.UK 디자인 시스템 지문 BBC의 글로벌 경험 언어(GEL) 파이낸셜 타임즈의 종이접기 햇빛재단 Apple의 휴먼 인터페이스 지침 스카이스캐너 백팩 메일침프 패턴 라이브러리 영감과 지침을 찾아볼 수 있는 환상적인 장소인 디자인 시스템 갤러리 에는 이러한 내용이 더 많이 나와 있습니다 . 게다가 시스템 형성에 대한 이야기가 있다면 기사나 블로그 게시물을 작성하는 것도 이를 문서화하는 완전히 합법적인 방법입니다. 뉴욕타임스는 디자인 시스템을 개발하면서 무엇을 했나요 ? 물론 그들은 그것에 관한 기사를 썼습니다 . 모든 형태의 디자인 문서를 출판하는 것은 약속이지만 목적에 대한 진술이기도 합니다. 아름다운 것을 공유해 보는 건 어떨까요? 그리고 유지하세요 # 이것은 모두 훌륭하고 좋습니다. 팔짱을 끼고 눈썹을 찌푸리며 말하는 것을 들었습니다. 하지만 누가 이 모든 것을 최신 상태로 유지할까요? 그것은 물건을 만드는 데 소비할 수 있는 모든 시간입니다. 나는 당신의 말을 듣고 있습니다. 때때로 이와 같은 트윗(X?)이 화제가 되는 이유는 다음과 같습니다. 디자인 시스템 구축 및 유지에 대한 디자인 밈 출처 : twitter.com ( 큰 미리보기 ) 그렇습니다. 열심히 일하고 조심해야 합니다. 설계 문서를 작성함으로써 절약할 수 있는 시간, 노력 및 마음의 고통은 동일한 것에 대한 투자 가치가 충분히 있을 것입니다. 문서가 안내하는 프로젝트와 더 잘 통합될수록 더 많은 유지 관리가 자체적으로 수행됩니다. 구성 요소와 모범 사례가 변경되고 일반적인 문제가 발생하고 해결됨에 따라 시스템과 해당 문서가 현물로 발전할 수 있습니다. “ 긴장감을 덜기 위해 디자인 문서가 처음부터 완벽할 수는 없습니다. 실수나 설명되지 않는 상황이 있을 텐데, 괜찮습니다. 소유하세요. 맹점을 인정하세요. 사용자가 피드백을 제공할 수 있는 방법을 포함합니다. 대부분의 디지털 작업과 마찬가지로 실제로는 "완료"되지 않습니다. 소규모로 시작 # 이렇게 철저하고 세련된 디자인 문서는 거의 억지력이 될 수 있으며, 이는 돈이 풍부한 사람만이 만들 수 있는 일입니다. 그것은 또한 정당화될 수 없는 시간 투자처럼 보일 수도 있습니다. 어느 쪽도 사실일 필요는 없습니다. 모든 양식을 문서화하면 장기적으로 시간이 절약되고 더 나은 결정을 내릴 수 있습니다. bash 스크립트든 뉴스레터 가입 구성 요소든 일회성 선택이 아닌 표준으로 적용할 때 좀 더 면밀히 조사해야 합니다. 읽어보기 중심의 정신을 당신의 마음에 두십시오 . 작게 시작하십시오. 글꼴과 색상을 선택하고 저장소 위키에 잘 어울리도록 표시하세요. 그게 다야! 진행 중입니다. 디자인 문서는 서로의 일부이기 때문에 프로젝트 자체를 관리하는 것처럼 디자인 문서도 관리하게 될 것입니다. 가서 문서화하세요!