MkDocs로 매뉴얼 만들기 #6 유지보수 — 검색, 접근성, 문서 문화

프레임워크 MkDocs Documentation Static Site
3 분 소요

#5까지 오면 다국어와 버전까지 갖춘 문서가 됩니다. 이제 만드는 단계는 끝났습니다. 문서는 한 번 만들고 끝나는 것이 아니라, 제품과 함께 계속 자라는 것입니다. 마지막 편에서는 그 문서를 오래 살아 있게 하는 운영을 다룹니다.

이번 시리즈는 MkDocs로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지
  • #2 nav와 검색 — 문서의 정보 구조 잡기
  • #3 콘텐츠 작성 — 코드블록, Mermaid, admonition
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기
  • #5 다국어와 버전 관리
  • #6 유지보수 — 검색, 접근성, 문서 문화 ← 이번 글

이번 글은 검색 다듬기, 모두를 위한 접근성, 문서를 살리는 문화 세 가지를 정리하겠습니다.

검색 다듬기 #

#2에서 봤듯 Material의 검색은 내장이라 따로 붙일 것이 없습니다. 다만 독자 경험을 더 끌어올리는 기능 몇 가지를 theme.features로 켤 수 있습니다.

mkdocs.yml — 검색 강화 
theme:
  name: material
  features:
    - search.suggest     # 입력 중 자동 완성
    - search.highlight    # 결과에서 검색어 강조
    - search.share        # 검색 결과 링크 공유

검색은 빌드 시점에 색인을 만들어 브라우저에서 도는 방식이라 서버가 필요 없습니다. 한국어 분절이 아쉽다면 #2에서 다룬 separator 조정을 함께 적용하면 됩니다.

모두를 위한 접근성 #

문서는 가능한 한 많은 사람이 읽을 수 있어야 합니다. Material은 기본 접근성이 양호하지만, 글을 쓰는 과정에서 깨지기 쉬운 지점이 몇 군데 있습니다.

  • 제목 위계를 건너뛰지 않습니다. 한 단계씩 내려가야 화면 낭독기가 구조를 제대로 읽습니다.
제목 위계 지키기 
# 페이지 제목 (h1, 페이지당 하나)
## 큰 절 (h2)
### 작은 절 (h3)
  • 링크 텍스트는 그 자체로 뜻이 통해야 합니다. “여기를 클릭"이 아니라 “설치 가이드"처럼 목적지를 적습니다.
  • 이미지에는 대체 텍스트를 답니다. 다이어그램을 Mermaid로 그리면 텍스트라 이 문제에서 자유롭습니다.
  • 색 대비를 지킵니다. Material의 색 팔레트를 손볼 때 본문과 배경의 대비가 WCAG AA 기준(4.5:1)을 넘는지 확인합니다.

문서를 살리는 문화 #

좋은 문서 도구를 갖춰도, 갱신이 멈추면 문서는 금세 거짓말이 됩니다. 오래 살아 있는 문서의 공통점은 도구가 아니라 습관입니다.

핵심은 #1에서 시작점으로 삼았던 Docs as Code를 끝까지 지키는 것입니다. 문서를 코드와 같은 저장소에 두고, 기능을 바꾸는 Pull Request 안에서 관련 문서도 함께 고칩니다. “문서 갱신"을 작업 완료 조건에 넣으면, 코드와 문서가 따로 노는 일이 줄어듭니다.

여기에 몇 가지를 더합니다. 글마다 최종 수정일을 드러내 오래된 글을 찾기 쉽게 하고(Material의 git-revision-date 플러그인이 자동으로 붙여 줍니다), 깨진 링크는 빌드 단계에서 점검하며, 큰 개편을 미루기보다 작게 자주 고칩니다. 완벽한 한 번의 정비보다, 꾸준한 작은 갱신이 문서를 살립니다.

시리즈를 닫으며 #

여섯 편에 걸쳐 MkDocs Material로 문서 사이트를 처음부터 운영까지 만들었습니다. 설치하고(#1), nav와 검색으로 구조를 잡고(#2), 코드블록과 admonition으로 내용을 채우고(#3), Cloudflare Pages로 배포하고(#4), 다국어와 버전을 더하고(#5), 끝으로 오래 유지하는 법(#6)까지 왔습니다.

블로그가 시간순 글 모음이라면, 문서 사이트는 구조화된 레퍼런스입니다. 그 차이가 도구 선택부터 운영 습관까지 전부를 갈랐습니다. 이제 여러분의 팀 문서를 이 흐름 위에 올려 보시길 바랍니다.

X