사람들이 계속 찾아오는 체인지로그 페이지 만드는 법

체인지로그 페이지는 사람들이 다시 돌아올 것이라면 만들 가치가 있다. 이것은 단순히 그것을 가지고 있는 것보다 더 높은 기준이며, 대부분이 걸려 넘어지는 기준이기도 하다. 존재하고, 푸터에 링크되어 있고, 몰아서 업데이트되며, 사고가 났을 때 말고는 아무도 방문하지 않는 페이지. 이 둘을 가르는 결정은 무언가 쓰이기 전에 내려지며, 대부분은 페이지가 어디에 있어야 하는지와 같은 콘텐츠에서 또 무엇이 생성되는지에 관한 것이다.

체인지로그 페이지란 무엇인가

제품에서 무엇이 바뀌었는지를 보여주는, 여러분 소유의 URL에 있는 공개되고 날짜가 적힌 목록이다. 같은 항목이 나타날 수 있는 다섯 가지 표면 중 하나이며, 유용한 질문은 어느 것을 고를지가 아니라 어느 것이 정본이고 어느 것이 거기서 생성되는지다.

정본이 되는 하나의 소스를 고르고, 한 번 발행하고, 나머지는 거기서 생성하라. 페이지와 위젯을 손으로 따로 유지하는 팀은 결국 서로 맞지 않는 두 개의 텍스트를 갖게 되고, 그 불일치는 고객이 발견한다.

체인지로그 페이지는 어디에 있어야 하는가

여러분 자신의 도메인에, 안정적인 경로로, 각 항목이 개별적으로 주소 지정될 수 있게. 세 가지 흔한 위치는 메인 사이트의 경로, 서브도메인, 문서의 한 섹션이다. 메인 사이트의 경로는 반대할 논거를 찾아야 하는 기본 선택지이지, 찬성할 논거를 찾을 것이 아니다. 사이트의 권위를 물려받고, 추가 인증서나 DNS가 필요 없으며, 페이지를 다른 모든 것과 같은 내비게이션에 유지한다.

서브도메인이 옳은 답이 되는 경우는 페이지가 마케팅 사이트와 다른 시스템에서 서비스될 때이며, 그렇지 않으면 프록시를 해야 할 것이다. 그 대가는 권위가 따로 쌓인다는 것이다. 체인지로그를 문서에 두는 것이 옳은 경우는 독자층이 개발자일 때이며, 그 이유는 API 체인지로그에서 다룬다. 독자는 보통 이미 거기에 있다.

선택보다 더 중요한 것은 항목이 개별적으로 링크될 수 있어야 한다는 점이다. 사람들은 사고 분석과 내부 티켓에서 항목을 링크한다. “체인지로그, 아래로 스크롤하세요”로만 링크할 수 있는 항목은 대신 스크린샷으로 붙여넣어진다.

체인지로그 페이지에는 무엇이 필요한가

다섯 가지가 있고, 처음 두 가지에서 대부분의 페이지가 실패한다. 변경 사항마다 날짜가 적힌 항목, 최신순으로. 관심 있는 유형별로 훑어볼 수 있도록 항목마다 카테고리나 라벨. 항목마다 고유 링크. 구독 경로. 약 50개 항목이 넘으면 검색이나 필터.

나머지는 선택 사항이다. 스크린샷은 도움이 되지만 유지 관리 비용이 든다. 저자 이름은 어떤 제품에서는 신뢰를 쌓고 다른 제품에서는 잡음이 된다. 버전 번호는 API 호출자에게는 중요하지만 그 외 거의 누구에게도 중요하지 않다. Keep a Changelog는 직접 라벨을 만들 이유가 없다면 합리적인 기본값이며, 나머지를 버리더라도 지킬 가치가 있는 핵심 규칙을 담고 있다. 로그는 사람을 위해 쓰인다는 것이다.

여러분의 제품이 연속적으로 출시된다면 버전이 아니라 날짜로 그룹화하라. “이것이 9일의 사고 전이었는지 후였는지”를 훑어보는 독자는 날짜를 찾고 있으며, 버전 번호로 정리된 페이지는 그에게 계산을 강요한다.

페이지인가, 앱 내 위젯인가

둘 다, 하나의 소스에서. 페이지는 검색, 링크, 긴 기록이 있는 곳이다. 위젯은 페이지를 절대 방문하지 않을 대다수 사용자에게 도달하는 방법이며, 그것이 작동하는 이유는 그들이 이미 사용하고 있는 제품 안에 나타나기 때문이다.

위젯의 실패는 방해다. 모든 항목에 주의를 요구하는 배지는 일주일 안에 영구적으로 무시되며, 이는 정말로 중요했던 항목을 위한 채널을 잃게 만든다. 독자가 마지막으로 본 이후로 읽지 않은 것을 세고, 첫 방문 시 조용히 카운터를 심어서 아무도 1년치 기록의 배지로 맞이하지 않게 하고, 독자 스스로 열게 하라. 대신 열어주지 마라.

체인지로그 페이지를 기계가 읽을 수 있게 만드는 법

같은 항목을 피드로도 발행하라. JSON 피드는 코드에서 그것을 소비하는 모든 것에 마찰이 가장 적은 선택지이며, RSS 피드는 리더에서 구독하는 개발자가 기대하는 것이다. 항목이 손으로 작성한 HTML 대신 구조화된 데이터가 되는 순간 둘 다 비용이 적게 든다. 이것이야말로 정본 사본을 구조화된 상태로 유지해야 하는 진짜 이유다.

페이지도 마크업하라. 항목은 날짜와 제목이 있는 작품이고, schema.org가 그 어휘를 제공한다. 이것은 고유 링크와 같은 이유로 가치가 있다. 브라우저가 아닌 것들, 고객 자신의 릴리스 프로세스를 포함해서, 페이지를 사용할 수 있게 만든다. 근본적인 항목이 애초에 구조화된 데이터였던 적이 없다면 이 중 어느 것도 작동하지 않는다; 체인지로그 파일 형식은 이 피드와 이 마크업이 실제로 생성되는 진실의 원천으로서 Markdown, JSON, YAML이 각각 무엇을 대가로 치르는지 다룬다.

체인지로그 페이지는 SEO에 도움이 되는가

간접적으로, 그리고 천천히. 개별 항목은 누군가 입력하는 어떤 검색어도 노리지 않기 때문에 순위에 잘 오르지 않는다. 페이지는 링크를 통해 자기 자리를 얻는다. 항목은 지원 답변, 포럼, 사고 분석에서 인용되며, 그 링크들은 여러분 소유의 URL에 쌓인다. 2년 동안 매주 업데이트되는 페이지는 그것이 속한 제품에 대한 신뢰할 만한 신선함 신호이기도 하다.

효과가 없는 것은 항목을 콘텐츠 마케팅처럼 다루는 것이다. 길이를 위해 세 문단으로 부풀려진 항목은 진짜 임무, 즉 독자가 사용하는 무언가가 바뀌었는지를 한 문장으로 말해주는 일을 더 못하게 된다. 체인지로그가 검색을 지원하기를 원한다면, 노력을 고유 링크, 피드, 그리고 그것으로 향하는 내부 링크에 쏟고, 항목은 짧게 유지하라. 우리 자신의 체인지로그 예시 페이지는 이 균형을 잘 잡는 페이지들을 모아놓았다.

사람들은 어떻게 구독하는가

이미 사용하는 경로를 제공하라. 개발자를 위한 RSS나 JSON 피드, 중요한 것만 듣고 싶은 사람을 위한 이메일, 그리고 둘 다 절대 하지 않을 모두를 위한 앱 내 위젯. 짐작하지 말고 무엇을 듣고 싶은지 물어보라. 파괴적 변경을 원하는데 문구 수정을 받는 독자는 둘 다에서 구독을 취소하기 때문이다.

마지막으로 추가해야 할 경로는 루프를 닫는 경로다. 어떤 항목이 특정 사람이 요청한 것을 해결했을 때, 그가 페이지를 읽어주기를 바라는 대신 직접 알려주라. changeloop에서는 항목이 페이지, 피드, 위젯에 한 번에 발행되며, 위젯 피드백이 pull request가 닫은 GitHub 이슈가 된 사람은 그 이슈에서 항목으로의 링크와 함께 통보받고, 위젯에서도 그 항목을 보게 된다. 메커니즘은 다른 구독과 동일하다. 차이는 수신자가 이미 물어봤다는 것이다. 이것이 체인지로그 쪽에서 피드백 루프 닫기에서 전개된 주장이다.

FAQ

체인지로그 페이지는 서브도메인에 있어야 하는가, 경로에 있어야 하는가? 기본적으로 메인 사이트의 경로다. 사이트의 권위를 물려받고 추가 인프라가 필요하지 않기 때문이다. 서브도메인은 다른 시스템이 페이지를 서비스할 때 정당화된다.

페이지는 한 번에 몇 개의 항목을 보여줘야 하는가? 화면을 채울 만큼, 그 이상은 아니고, 이후에는 페이지네이션. 2년치 기록을 하나의 문서에 로드하는 것은 느리고 최신 항목을 찾기 어렵게 만든다.

오래된 항목은 언젠가 삭제해야 하는가? 아니다. 여러분 사이트 밖에서 인용되고 있으며, 링크가 깨진다. 항목은 그 자리에서 메모와 함께 수정하고, URL은 계속 살아 있게 하라.

모든 변경 사항이 페이지에 나타나야 하는가? 사용자가 알아챌 수 있는 것만. 내부 리팩터링을 기록하는 페이지는 독자가 대충 훑어보도록 훈련시키며, 대충 훑어지는 페이지는 긴급한 무언가를 담고 있는 날 실패한다.

이 글의 기술적 내용은 독립적으로 검토되지 않았습니다. 잘못된 부분이 있으면 알려 주세요. 바로잡겠습니다.

changeloop 관련 페이지: changelog 예시, 개발자 문서