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