웹 운영
릴리스 노트 발행 전 Markdown 미리보기 체크리스트
블로그나 도움말 페이지에 릴리스 노트를 올리기 전에 Markdown 제목, 링크, 코드블록, 이미지, CTA를 점검하는 실무 체크리스트입니다.
검색 의도: 편집기에서는 멀쩡했는데 발행 후 깨지는 문제 막기
릴리스 노트는 티켓 요약에서 Markdown, Slack, 블로그, 도움말 페이지로 빠르게 옮겨지는 경우가 많습니다. 내용은 맞아도 발행된 화면에서는 작은 문제가 보일 수 있습니다. 제목 단계가 건너뛰어지거나, 목록이 한 문단처럼 붙거나, 코드블록이 다음 문단까지 삼키거나, 긴 URL이 불필요한 프리뷰로 화면을 덮는 식입니다. 독자는 업데이트 내용보다 형식 오류를 먼저 보게 됩니다.
발행 전에는 Markdown을 실제 화면처럼 미리보고 방문자 입장에서 한 번 읽어야 합니다. Sambro의 Markdown 미리보기 도구는 https://tools.sambro.space/ko/tools/markdown-preview 에서 바로 쓸 수 있습니다. JSON 예시가 있으면 https://tools.sambro.space/ko/tools/json-formatter 로 먼저 정리하고, 제목이나 요약이 카드·Slack 보고에 들어간다면 https://tools.sambro.space/ko/tools/word-counter 로 길이를 확인해 핵심 변화가 잘 보이게 만듭니다.
문장 다듬기보다 구조를 먼저 본다
좋은 릴리스 노트는 무엇이 바뀌었는지, 누가 영향을 받는지, 어떤 행동이 필요한지, 다음에 어디로 가야 하는지를 빠르게 알려 줍니다. Markdown에서는 이 구조가 제목 단계로 드러납니다. H1이나 페이지 제목은 하나면 충분하고, 주요 변경, 수정 사항, 알려진 문제, 관련 링크는 H2 단위로 나누는 편이 읽기 쉽습니다. 글자가 작아 보인다는 이유만으로 제목 단계를 고르면 검색과 접근성 모두에 좋지 않습니다.
첫 구조를 잡은 뒤 바로 미리보기를 봅니다. 렌더링 화면에서 섹션이 너무 잘게 쪼개져 보이면 합치고, 중요한 행동 안내가 긴 배경 설명 아래에 묻혀 있으면 위로 올립니다. 검색으로 들어온 방문자와 기존 고객 모두 가장 먼저 알고 싶은 것은 같습니다. 무엇이 바뀌었고, 그 정보로 지금 무엇을 하면 되는가입니다.
링크, 코드블록, 이미지는 같이 점검한다
링크는 편집기가 아니라 미리보기 화면에서 직접 열어 봐야 합니다. 공개 경로인지, 언어 경로가 맞는지, localhost나 preview URL이 남아 있지 않은지 확인합니다. Sambro 기준 링크는 회사 맥락은 https://sambro.space/, 도구는 https://tools.sambro.space/ko/tools, 블로그는 https://blog.sambro.space/ 로 분리해 두면 독자가 목적지를 예측하기 쉽습니다.
코드블록도 같은 방식으로 봅니다. 시작과 끝이 정확한지, 필요한 경우 언어 라벨이 있는지, 명령 결과가 다음 문단까지 감싸지 않는지 확인합니다. 화면 캡처가 필요하다면 업로드 전에 https://tools.sambro.space/ko/tools/image-compressor 로 용량을 줄이고, 작은 UI 글자가 실제 표시 크기에서 읽히는지도 봅니다. 릴리스 노트는 텍스트만이 아니라 제목, 링크, 예시, 이미지가 합쳐진 발행물입니다.
비공개 맥락과 과도한 공유를 제거한다
Markdown은 티켓, 터미널, 채팅 내용을 그대로 붙여 넣기 쉽기 때문에 미리보기 단계에서 개인정보와 내부 정보를 따로 봐야 합니다. 내부 호스트명, 서명 URL, 토큰, 고객명, 비공개 이슈 링크, 무관한 브라우저 탭이나 알림이 보이는 이미지는 제거합니다. URL 인코딩은 공개 허용이 아닙니다. 쿼리 값을 설명해야 한다면 안전한 예시 형태로 바꾸고 URL 도구로 그 형태만 확인합니다.
시간, 버전 번호, 기능명, 제품명도 일관되게 맞춥니다. 릴리스 노트는 배포 직후뿐 아니라 오래 뒤 검색으로도 읽힐 수 있습니다. 오늘, 최근, 다음 주 같은 표현은 시간이 지나면 애매해집니다. 일정이 중요한 경우 안정적인 날짜를 쓰고, CTA는 Slack 스레드가 사라진 뒤에도 의미가 남는 공개 목적지로 연결합니다.
실무용 Markdown 미리보기 체크리스트
마지막 점검 순서는 고정해 둡니다. 제목이 페이지에 맞는지, 제목 단계가 자연스러운지, 요약이 세부사항보다 먼저 나오는지, 목록이 제대로 렌더링되는지, 코드블록이 닫혔는지, 링크가 공개 경로로 열리는지, 이미지는 가볍고 읽을 수 있는지, 비공개 맥락이 제거됐는지, 날짜가 안정적인지, CTA가 다음 행동으로 이어지는지 확인합니다. 그리고 모바일 채팅에서 열리는 경우를 고려해 좁은 화면에서도 한 번 읽습니다.
Sambro 흐름에서는 Markdown 미리보기, 글자수 세기, JSON 포맷터, URL 도구, 이미지 압축을 함께 쓰면 발행 직전 실수를 줄일 수 있습니다. 목표는 릴리스 노트를 길게 만드는 것이 아닙니다. 고객, 팀원, 미래의 유지보수자가 빠진 티켓 맥락을 다시 묻지 않고도 이해할 수 있는 깨끗하고 검색 가능한 업데이트를 남기는 것입니다.