GitHub README는 프로필이 아니라 매장 페이지입니다 — 작성자가 적용한 5가지 규칙

AI 요약

글쓴이는 GitHub 프로필을 이력서나 장식 공간이 아니라 제품 페이지로 다룹니다. 방문자가 이름을 다 읽기도 전에 대표 앱을 내려받도록 만드는 것이 목표입니다. 앱을 만드는 사람이라면 README에서 무엇을 보여줄지 나열하는 데 그치지 말고, 방문자가 취할 행동을 바로 제공해야 한다고 설명합니다.

방문자가 할 행동을 앞세웁니다

글쓴이는 데스크톱 앱 ATLOCK, APIC, ANOTE, ACALCU를 소개합니다. 각 앱을 카드로 보여주고 카드 바로 아래에 실제 .zip 릴리스로 연결되는 다운로드 버튼을 둡니다. 릴리스 페이지를 찾아 들어가는 단계를 없앴습니다. 작가라면 대표 글을 카드로 보여주고, 라이브러리 작성자라면 npm i your-lib를 첫 화면에 둘 수 있다고 제안합니다.

색과 너비를 통일합니다

페이지 전체에 금색 계열인 #B8935F와 그림자 색 #8a6c3f를 씁니다. 로고, 섹션 제목, 버튼, 카드 테두리까지 같은 색을 적용합니다. 전체 너비 이미지는 830px로 맞추고 앱 카드는 408px로 제작해 두 장과 간격이 한 줄 안에 들어가도록 합니다. 요소마다 크기가 달라 보이는 위젯 더미 대신 하나의 열처럼 읽히게 구성합니다.

제목을 터미널 형식으로 맞춥니다

섹션 이름은 ‘About Me’나 ‘Projects’ 대신 ~/links, ~/apps, ~/status, ~/stack으로 씁니다. 글쓴이는 이런 표기가 터미널을 사용하는 개발자의 페이지라는 점을 빠르게 드러내고, 제목의 위치와 모양을 통일해 훑어보기 쉽게 만든다고 설명합니다.

제품 철학을 한 문장으로 보여줍니다

페이지 중간에는 “Zero telemetry. Zero cloud. Zero subscriptions. Zero ads.”라는 배너를 둡니다. 글쓴이의 제품 철학을 소개 문구가 아닌 이미지 한 장으로 전달합니다. 마지막에는 “Your machine. Your data. Your control.”이라는 문장으로 마무리합니다. 글쓴이는 방문자가 항목 목록보다 기억하고 되풀이할 수 있는 문장을 더 잘 기억한다고 말합니다.

이미지를 직접 관리하고 접근성을 챙깁니다

프로필의 카드와 배너, 머리말, 바닥글 이미지를 모두 저장소의 /assets에 SVG로 보관합니다. 외부 서비스의 통계 카드나 연속 기록 위젯은 사용하지 않습니다. 서비스가 멈추거나 URL이 바뀌면 이미지가 사라질 수 있기 때문입니다. 이미지는 raw.githubusercontent.com의 절대 URL로 불러와 README를 복사하거나 미러링해도 표시되도록 하고, 배너를 포함한 이미지마다 대체 텍스트를 작성해 스크린 리더와 이미지 로딩 실패 상황도 고려합니다.

페이지는 링크, 앱, 상태, 기술 스택, 소개 이미지와 바닥글 등 여섯 섹션으로 구성하며, 각 앱에 하나의 행동 버튼을 둡니다. 글쓴이는 프로필이 맡을 역할을 정한 뒤 그 역할에 맞는 행동을 버튼으로 만들라고 권합니다.

dev.to 반응

• @danielecangi — 정말 마음에 듭니다. 잘 정리됐고 인상적입니다. 제 취향은 아닙니다. 사이버펑크가 떠오르지만, 지금 하시는 일에는 잘 어울립니다. 🦾
  • @akhourianmolkumar — 프리미엄 README와 멋진 매장 페이지를 합친 느낌을 내려 했습니다.
• @georgekobaidze — 언급해 주셔서 감사합니다. 작성하신 버전도 정말 마음에 듭니다. 잘하셨어요! 🔥
  • @akhourianmolkumar — 형이 트렌드를 시작해 줬습니다. 예전 README를 멋진 매장 페이지로 바꾸도록 영감을 줘서 고맙습니다.
  • @georgekobaidze — 간접적으로라도 도움이 됐다니 기쁩니다!
  • @akhourianmolkumar — 형은 통계 기능을 쉽게 관리하는 것 같습니다. 그런데 다운로드 카운터를 설정했더니 제대로 작동하지 않아 놀랐습니다. 자동 실행은 안 되고 워크플로를 직접 실행해야 했습니다. 어떻게 관리하시나요?
  • @georgekobaidze — 자동 예약 워크플로가 작동하지 않았다는 뜻인가요? 그렇다면 실행이 예약 시간보다 늦어질 때가 있습니다. 그래도 결국 실행됩니다.
  • @akhourianmolkumar — 3시간을 기다렸습니다. 30분마다 갱신하도록 설정했는데요. 다시 설정해 보겠습니다.
  • @georgekobaidze — 매일 갱신해 보세요. 저는 하루에 한 번 설정했는데도 보통 늦게 실행됩니다. 예약 실행이 많고 부하가 높아서 그런 것 같습니다.
  • @akhourianmolkumar — 아, 24시간마다 갱신하는 거군요. 하루에 한 번 자동 갱신하도록 설정하겠습니다. 일단 문제를 해결하려고 README에서 다운로드 상태 표시를 아예 뺐습니다. ㅋㅋ
  • @georgekobaidze — 네, 그런 통계는 24시간에 한 번이면 괜찮습니다. 너무 자주 갱신하지 않으면서 데이터도 너무 오래된 상태로 남지 않습니다.
  • @akhourianmolkumar — 이제 LinkedIn과 dev.to에서도 연결됐네요. 우리 형제 맞죠? 🤝
  • @georgekobaidze — 하하, 물론이죠 😄 DEV 형제들이네요 😂
  • @akhourianmolkumar — 해커톤 두 번 우승한 사람의 형제가 되어 자랑스럽습니다 🤝
  • @georgekobaidze — 😂 너무 심각하게 받아들이지 마세요. 저는 만드는 걸 좋아하는 사람일 뿐입니다 😄
  • @akhourianmolkumar — 그냥 사람이라니요 ㅋㅋ 해커톤 두 번 우승한 사람을 그냥 사람이라고 하는 건 처음 봅니다. 😂
  • @georgekobaidze — 😄
  • @akhourianmolkumar — ☠️😂
• @viniciusvts — 공유해 주셔서 감사합니다. 제 프로필을 개선하는 데 도움이 되겠습니다.
• @pengeszikra — 저도 README.md의 깊은 구덩이에 빠졌습니다. 그래도 이력서는 한 줄로 압축했습니다. “mordorjs와 TifY를 만든 사람이며 pipeline-operator 광팬입니다.” 🇭🇺 자리표시자 이미지는 새로운 무언가의 시작일 뿐이고, 앞으로 준비할 예정입니다. 제 GitHub 프로필에서 가장 중요한 부분은 dev.to 게시물에서 저장소로 연결하는 링크입니다.
• @shieldxbot — README를 매장 페이지로 보는 관점은 많은 개발자가 놓칩니다. 화려한 배지나 기여 그래프에 매달리면 채용 담당자나 협업자가 실제로 무엇을 만들 수 있는지 알기 어렵습니다. 기술 목록만 보여주기보다 ‘왜’와 ‘어떻게’에 집중하는 프로필이 효과적이라고 생각합니다. React나 Go를 나열하는 대신 간단한 아키텍처 설명이나 직접 해결한 문제를 잘 문서화한 링크를 보여주면 더 강한 인상을 줍니다. README 자체를 과하게 만드는 점도 주의해야 합니다. 프로필을 관리하는 시간이 실제 프로젝트에 쓰는 시간보다 길어지면 매장 페이지가 아니라 방해물이 됩니다. 문서는 간결하게 유지하고 코드가 제 역할을 하게 두세요.

원문: dev.to / 번역·요약: Trawling