목록으로
'언젠가 읽기' 컨텐츠는 논문이나 영문 컨텐츠 등 언젠가 읽으려고 즐겨찾기 하고선 읽지 않고 계속 미룰만한 컨텐츠를 읽고 요약하거나 소개합니다.

우리는 Diátaxis 프레임워크로 문서를 개선했습니다.

언젠가 읽기
2025. 2. 4. PM 5:00:35
#Sequin #Diátaxis Framework #Documentation #Tutorials #How-to Guides

문서 개선을 위한 디아택시스 프레임워크 도입

개요

Sequin 팀은 최근 Diátaxis 프레임워크를 도입하여 문서화를 개선했습니다. 초기에는 엔지니어링 관점에서 모든 것을 설명하려 했지만, 사용자들이 제대로 이해하지 못하는 문제를 겪었습니다. Diátaxis를 통해 문서를 네 가지 카테고리로 구분함으로써 사용자 경험을 향상시킬 수 있었습니다.

엔지니어의 문서화 오류

엔지니어들은 문서를 작성할 때 제품의 작동 방식과 개발 이유를 먼저 설명하려는 경향이 있습니다. Sequin 팀도 초기에는 "Sequin의 작동 방식"을 첫 번째 문서로 사용했으나, 이는 사용자들이 제품을 실제로 사용해보기 전까지는 제대로 이해하지 못하게 만들었습니다.

Diátaxis란?

Diátaxis는 문서화를 위한 프레임워크로, 모든 문서를 네 가지 카테고리로 분류합니다. 각 카테고리는 작성 방법에 대한 지침을 제공하며, 독자들이 자연스럽게 문서를 탐색할 수 있도록 돕습니다.

네 가지 문서 카테고리

  1. 튜토리얼 (Tutorials)
    • 초보자가 실습을 통해 배우는 교훈 형식의 문서.
    • 특정 목표를 향해 단계별로 안내하며, 독자가 별도의 결정 없이 따라갈 수 있도록 구성됨.
  3. How-to 가이드 (How-to guides)
    • 사용자가 원하는 목적을 달성할 수 있도록 단계별로 안내.
    • 구체적인 예시보다는 다양한 상황에서 문제를 해결할 수 있는 방법을 제공.
  5. 참고 자료 (Reference)
    • 기술적인 정보로, 사용자가 작업 중에 필요할 때 빠르게 참고할 수 있는 문서.
    • API 문서나 명령어 참조 등이 이에 해당.
  7. 설명 (Explanation)
    • 배경 지식과 이해를 돕는 문서.
    • "왜"라는 질문에 답하며, 깊이 있는 이해를 제공.

도입 결과

Diátaxis 프레임워크를 도입한 후, Sequin의 문서는 사용자들이 보다 쉽게 이해하고 활용할 수 있게 되었습니다. 특히, 각 카테고리에 맞는 문서 작성으로 사용자 경험이 크게 향상되었습니다.

참고 자료

  • Diátaxis 공식 웹사이트
  • HN 뉴스 기사
  • Sequin GitHub 저장소
[ 출처] We fixed our documentation with the Diátaxis framework
푸딩캠프 뉴스레터를 구독하면 학습과 성장, 기술에 관해 요약된 컨텐츠를 매주 편하게 받아보실 수 있습니다.