Documentation
릴리스 노트 게시 전 마크다운 미리보기 체크리스트
릴리스 노트, README 수정, 도움말 문서를 공개하기 전에 마크다운 미리보기로 제목, 코드 블록, 링크를 확인하는 실무 체크리스트입니다.
검색 의도: 올리고 나서야 마크다운이 깨진 것을 발견하지 않기
릴리스 노트와 README 수정은 내용보다 표시 형태에서 작은 사고가 자주 납니다. 표가 모바일에서 밀리고, 코드 블록이 닫히지 않아 다음 문단까지 회색 박스 안에 들어가고, 체크리스트가 일반 문장처럼 보이고, 링크가 공개 페이지가 아니라 내부 초안으로 연결되는 식입니다. 작성한 원문이 아니라 독자가 보는 렌더링 결과가 실제 문서입니다.
게시 직전에는 https://tools.sambro.space/ko/tools/markdown-preview 같은 브라우저 마크다운 미리보기로 한 번 보는 편이 안전합니다. 무거운 문서 빌드 환경을 열지 않아도 원문과 렌더링 결과를 빠르게 비교할 수 있습니다.
독자가 다음에 해야 할 행동부터 정하기
미리보기 전에 이 문서를 읽은 사람이 무엇을 해야 하는지 정합니다. 릴리스 노트라면 설정을 바꿔야 하는지, 새 기능을 확인해야 하는지, 내부 변경이라 그냥 알아두면 되는지 구분해야 합니다. README라면 설치, 실행, 검증까지 이어져야 합니다. 이 행동이 정해져야 제목, 목록, 코드 블록, 링크의 우선순위가 보입니다.
이 기준이 없으면 미리보기는 단순한 예쁜 화면 확인으로 끝납니다. 보기 좋은 릴리스 노트라도 마이그레이션 단계를 숨기면 좋지 않습니다. 반대로 투박한 문서라도 명령어, 예상 결과, 되돌리는 링크가 분명하면 바쁜 상황에서 훨씬 쓸모가 있습니다.
실무에서 쓰기 좋은 확인 순서
게시 직전에는 순서를 고정합니다. 먼저 마크다운 원문을 미리보기에 붙여 넣고, 제목 계층을 위에서 아래로 훑고, 코드 펜스와 인라인 명령어를 확인하고, 문서 밖으로 나가는 링크를 열어 보고, 각 섹션의 첫 문장과 마지막 문장을 읽습니다. 이 정도만 해도 대부분의 표시 오류와 흐름 오류를 잡을 수 있습니다.
릴리스 노트라면 날짜, 버전, 제품명이 서로 맞는지도 봅니다. README라면 사용자가 복사해야 하는 명령어와 예상 출력이 섞이지 않게 분리합니다. JSON 예시가 들어간다면 먼저 https://tools.sambro.space/ko/tools/json-formatter 로 정리한 뒤 코드 블록에 넣는 편이 읽기 쉽습니다.
게시 전 자주 하는 실수
첫 번째 실수는 에디터 원문만 믿는 것입니다. 원문은 가지런해 보여도 들여쓰기, 빈 줄, 빠진 백틱 하나 때문에 공개 화면이 깨질 수 있습니다. 두 번째 실수는 링크 문구를 여기, 이 페이지처럼 흐리게 쓰는 것입니다. 링크 텍스트는 독자에게 목적지를 알려주고 검색에도 맥락을 줍니다.
공개 문서에 내부 정보를 남기는 것도 주의해야 합니다. 내부 티켓 ID, 비공개 URL, 토큰, 고객명, 임시 디버깅 메모는 게시 전에 제거하거나 일반 표현으로 바꿔야 합니다. 마크다운 미리보기는 포맷뿐 아니라 공개해도 되는 내용인지 다시 보는 단계로 쓰면 좋습니다.
Sambro 도구를 쓰는 위치
작은 문서 수정이 곧바로 공개될 때 https://tools.sambro.space/ko/tools/markdown-preview 로 빠르게 렌더링을 확인하면 됩니다. 같은 업데이트에 이미지가 들어가면 https://tools.sambro.space/ko/tools/image-compressor 로 파일을 가볍게 만들고, 짧은 설명 필드가 있다면 https://tools.sambro.space/ko/tools/word-counter 로 길이를 먼저 확인할 수 있습니다.
기준은 단순합니다. 문서를 미리보고, 독자의 행동 경로를 확인하고, 링크를 열어 보고, 다음 사람이 질문 없이 따라갈 수 있는 상태로만 게시합니다. 회사 소개나 서비스 문의 맥락은 https://sambro.space/ 를 기준으로 확인하면 됩니다.