[번역] API를 위한 최소한의 실행 가능한 문서(Minimum Viable Documentation)
최소 실행 가능한 문서 세트(Mininum Valuable Document)는 대다수의 개발자가 기꺼이 API를 채택할 수 있도록 필요한 최소한의 문서로, API가 시간을 낭비하기 때문에 좌절하거나 포기하지 않을 만큼의 최소한의 문서입니다.
최소 실행 가능한 문서 세트(Mininum Valuable Document)는 대다수의 개발자가 기꺼이 API를 채택할 수 있도록 필요한 최소한의 문서로, API가 시간을 낭비하기 때문에 좌절하거나 포기하지 않을 만큼의 최소한의 문서입니다.
개발자가 API에 대해 좌절할 때 그 이유는 정보가 빠졌거나, 불완전하거나, 찾기가 너무 어렵기 때문입니다. 예를 들어, 코드 샘플이 없거나 튜토리얼이 없거나 때로는 API가 어떻게 작동하는지에 대한 높은 수준의 정보가 없는 때가 있습니다.
MVD에는 새로운 사용자가 시작하는 데 필요한 가장 중요한 정보가 포함되어 있고 이를 더 쉽게 찾고 사용할 수 있는 방식으로 분류되어 있습니다.
다음은 API에 대한 최소한의 실행 가능한 문서를 갖추기 위해 필요한 세 가지 문서 유형입니다:
- 레퍼런스: REST API의 경우 엔드포인트, 해당 메서드, 요청에 사용할 수 있는 매개변수, 응답에 반환할 수 있는 속성의 전체 카탈로그를 의미합니다. 참조 섹션의 경우 완전성과 정확성이 매우 중요합니다. 설명이 전혀 없는 매개변수만큼 사용자를 화나게 하는 것은 없습니다.
- 빠른 시작 또는 시작하기 문서: 이 문서는 사용자가 API를 통해 어떤 작업을 완료하는 데 가장 짧은 경로를 보여줌으로써 API의 작동 방식을 이해하고 그 이점을 이해할 수 있도록 해야 합니다.
- API의 기능, 작동 방식, 해결 방법 및 사용자가 API를 채택하기 전에 이해해야 할 기타 고급 정보를 설명하는 개요.
이 아키텍처가 정확히 세 부분으로 구성되어야 하는 강력한 이유가 있습니다.
다양한 유형의 사용자
첫째, 다양한 유형의 사용자가 있고, 각 유형의 사용자의 기대가 전부 다르기 때문에 세 가지 유형의 문서가 모두 필요합니다.
일부 API는 레퍼런스만 제공하지만, 이는 모든 잠재적 사용자를 만족시키기에 충분하지 않습니다. (레퍼런스 문서를 생략하는 경우는 거의 없지만 완성도가 부족하면 사용자가 외면하게 됩니다.)
API 사용자가 문서를 시작하는 방법과 문서를 사용하는 방법은 다릅니다. 어떤 개발자는 레퍼런스 섹션에서 코드를 복사하고 수정 코드로 바로 작업합니다. 어떤 개발자는 튜토리얼이나 빠른 시작을 따라서 예제 작업을 완료한 후 실제 작업으로 넘어갑니다. 소수는 개요(및 일부 지원 정보)를 볼 수 있을 때까지 API를 채택하지 않으려 합니다.
기술을 사용할 때 겪는 어려움은 대부분 처음에 생깁니다. 따라서 개발자가 API 사용을 시작하는 방법에 주의를 기울여야 합니다. 개발자가 포기하고 다른 제품을 사용해 보지 않도록 올바른 정보를 제공하는 것이 중요하며 포기하지 않을 만큼 쉽게 학습할 수 있도록 돕는 것도 중요합니다.
다양한 유형의 정보
MVD에 정확히 세 가지 유형의 문서가 있는 것은 우연이 아닙니다. 개발자에게 필요한 모든 정보를 하나의 문서에 모두 담을 수 없는 이유가 궁금할 텐데요.
MVD의 세 가지 문서는 모든 종류의 기술 및 비기술 문서에 자연스러운 정보 유형에 해당합니다. 사람들이 문서를 사용하는 방식을 고려해서 분리해 두는 것이 가장 좋습니다.
먼저 정보의 유형은 다음과 같습니다.
개념 정보
아이디어를 설명하는 데 사용되는 비교적 개방적인 형식의 정보입니다. 개념 정보는 다른 두 가지 유형만큼 구조화되어 있지 않으며 그 목표는 이해입니다. MVD에서는 개요에 대부분의 개념 정보가 포함되어 있습니다.
참조 정보
일관되게 구조화된 항목의 사전과 같은 정보 모음으로, 일반적으로 독자가 정확한 데이터 항목을 찾고자 할 때 참조합니다. MVD에서 API 참조 섹션에는 모든 참조 정보가 포함되어 있습니다.
작업을 위한 정보
독자의 목표가 특정 작업을 완료하는 것일 때 독자에게 작업을 완료하는 방법을 알려주는 일련의 단계 정보입니다. MVD에서는 ‘빠른 시작’에 해당합니다.
Joanna Bujes는 2016년 UC 버클리 익스텐션에서 소프트웨어 테크니컬 라이팅을 가르칠 때 이러한 개념을 독특한 방법으로 소개했습니다. 가을 학기 초 어느 날 저녁, Bujes는 자신의 서가에 꽂혀 있던 책들을 한 아름 들고 작은 강의실을 돌아다녔습니다. 그녀는 모든 학생 앞에 각기 다른 요리책을 놓았습니다. Bujes교수는 기술 문서와 마찬가지로 각 요리책이 위에서 소개한 세 가지 정보 유형을 사용한다고 강조했습니다.
- 개념 정보: 소개(개요) 장에서는 육류, 생선, 농산물 및 기타 재료를 선택하고 보관하는 방법, 빵을 구울 때 어떤 종류의 장비를 사용해야 하는지, 반죽을 다루는 방법 등을 설명합니다.
- 참조 정보: 예를 들어, 과일의 파운드와 과일을 보관하는 데 필요한 병의 개수를 비교한 표가 있습니다.
- 작업을 위한 정보: 모든 요리책에는 수많은 레시피를 조리하기 위한 단계별 지침이 포함되어 있습니다.
요리책은 자료를 개념, 참조, 작업으로 구분하는 유형이 정보를 유기적이고 자연스럽게 정리하는 방법이라는 것을 보여주기 때문에 기술 문서에 대한 좋은 비유가 될 수 있습니다. 이 세 가지 문서 유형을 사용하면 독자는 원하는 정보를 원하는 때에 쉽게 찾을 수 있습니다.
다시 말해 독자들은 참조, 작업, 개념 정보를 서로 다른 시기에 서로 다른 이유로 사용할 가능성이 높습니다. 그래서 각 정보를 구분해두면 독자가 원하는 정보를 어디서 찾아야 하는지 알 수 있고 당장 해야하는 작업과 관련 없는 불필요한 정보를 헤매지 않아도 됩니다.
요리책을 예로 들어 봅시다. 대부분의 사용자는 '빵' 챕터가 시작되는 설명 문서에서 빵을 만드는 법에 대한 다양한 설명을 보고 싶어합니다. 책을 자주 보는 사용자는 짜리 참조 문서 섹션에서 다양한 밀가루 종류만 보게 될 겁니다.
저자가 이 모든 정보를 반 페이지 이하의 레시피와 결합하여 빵을 굽는다고 상상해 보세요. 작업 단계에 섞여 있는 불필요한 정보를 모두 훑어봐야 하기 때문에 각 레시피를 따라하는 것은 더 길고 어려운 작업이 될 것입니다. 나중에 통곡물 가루와 밀기울 가루의 차이점을 알고 싶을 때 두 가루에 대한 설명을 각각 어디서 봤는지 기억하는 데 엄청난 시간이 걸릴 것입니다.
같은 이유로 우리는 소프트웨어 문서를 작성할 때 개념 정보, 참조 정보, 작업 정보를 한 번에 작성하지 않습니다.
MVD가 문서에 주는 이점
문서 작업을 할 때 MVD를 고려하면 궁극적으로 얻을 수 있는 이점은 두 가지입니다.
- 단기간에 학습 능력이 크게 향상됩니다.
- 장기적으로 지속적인 사용자를 위한 사용 편의성이 완만하게 증가합니다.
학습 용이성(learnability) 향상
학습 용이성은 API 채택에 있어 가장 중요한 지표입니다. MVD는 학습 용이성에 관한 것입니다. 다양한 상황에 처한 다양한 사용자에게 핵심 정보를 제공해서 모든 사용자에게 필요한 정보를 제공할 수 있습니다.
소프트웨어 문서에서 학습 용이성이 중요한 이유 중 하나는 소프트웨어 사용의 어려움이 대부분 처음에 생기기 때문입니다. 사람들이 좌절감을 느끼고 소프트웨어 사용을 그만두는 것은 대부분 소프트웨어를 시작한 지 얼마 지나지 않아서일 가능성이 높습니다. 사용자 수를 늘리는 가장 좋은 방법은 최대한 쉽게 사용할 수 있도록 만드는 것입니다.
사람들은 쉽게 사용할 수 있는 소프트웨어를 선택하는 경향이 있습니다. API를 만드는 사람들은 효과적인 문서화가 수익 창출의 원동력이라는 사실을 발견해 왔습니다. 최고의 문서를 가진 사람이 최고의 딜을 따낼 수 있기 때문이죠. (개발자의 경험을 활용하여 시장에서 입지를 넓힌 회사의 좋은 예가 바로 Stripe입니다.)
지속적인 사용자를 위한 사용성 향상
사용자의 첫 진입을 유도하는 것 만큼, 문서가 채택된 후에도 지속적으로 사용할 수 있도록 하는 것도 중요합니다. MVD 모델은 이러한 이유로 계속해서 성과를 거두고 있습니다.
- 레퍼런스 문서의 철저함은 MVD의 기초이고 사용자의 지속적인 사용을 위해서도 중요합니다.
- MVD를 적용한다는 것은 사용자가 필요할 때 필요한 것을 더 쉽게 찾을 수 있도록 정보를 개념, 작업, 참조로 구성한다는 것을 의미합니다. 찾기가 쉬워지면 시간과 노력이 절약됩니다.
MVD가 다루지 않는 것
MVD는 새로운 문서 세트를 시작하거나 기존 문서의 완성도를 평가하기 위한 프레임워크입니다. 이 프레임워크가 문서에 대한 모든 질문에 대한 답을 주진 못합니다. 다음은 이 MVD가 다루지 않는 부분입니다.
- 품질 측정: MVD는 문서가 잘 작성되었는지 여부가 아니라 최소한의 요소가 모두 포함되어 있는지를 알려줍니다. (이에 대해서는 나중에 자세히 설명하겠습니다.)
- 성숙도 측정: 제품이 성숙해지면 문서도 함께 성숙해져야 합니다. 최소한의 문서만 갖추게 되면 곧 그것만으로는 충분하지 않다고 판단하게 될 것입니다. 사용자들은 빠른 시작 외에도 작업을 완료하는 데 사용하는 워크플로우를 다루기 위해 더 많은 작업을 추가하기를 원할 것입니다. 성숙한 문서에는 MVD의 모든 요소와 그 이상이 포함되어 있습니다.
- 장기적인 문서 아키텍처 제공: 처음에는 세 개의 간단한 섹션으로 구성해도 괜찮을지 모르지만 나중에는 문서가 더 복잡해지기 때문에 이를 체계적으로 정리할 수 있는 합리적인 방법을 마련해야 합니다. 요리책을 다시 생각해 봅시다. 요리의 즐거움은 수년에 걸쳐 수천 개의 레시피를 추가하도록 확장되었고, 칵테일, 냉동 디저트, 기본 재료에 대해 설명하는 챕터가 추가되거나 삭제되었다가 다시 복원되었습니다. '요리의 즐거움'이나 다른 잘 디자인된 책의 목차를 살펴보면 구성 원칙이 항상 사용자의 요구 사항이어야 한다는 것을 알 수 있습니다. 독자는 누구입니까? 무엇을 성취하려고 하나요? 그러기 위해 무엇을 알아야 할까요? 어떤 순서로 알아야 할까요?
더 읽어보기
이제 MVD를 구성하는 세 가지 문서 유형을 이해했습니다. 다음으로 생길 질문은 각 문서 유형을 어떻게 작성하는지에 대한 것일 텐데요.
새로운 문서 세트를 시작하거나 기존 문서를 개선할 준비가 되었다면 각 문서 유형에 대한 GitHub의 콘텐츠 체크리스트를 살펴보세요.