깃허브 프로필 프로젝트 섹션을 토글로 정리해 가독성 개선

GitHub 프로필 README를 또 손댔다. Featured Projects 두 번째 row를 <details> 토글로 접어서 "More Projects" 형태로 분리하는 작업이었는데, 작업 자체는 20분이면 끝나는데 왜 이렇게 하는지 정리해두는 게 나중에도 도움이 될 것 같아서 써둔다.

GitHub 프로필을 왜 계속 다듬냐면, 채용 담당자나 협업 제안이 들어올 때 이력서보다 GitHub 링크를 먼저 여는 경우가 꽤 많기 때문이다. 링크드인 메시지에 "GitHub 보고 연락드렸어요"라는 패턴이 생각보다 자주 온다. 첫인상은 5초 안에 결정된다는 얘기가 괜히 있는 게 아니고, 스크롤을 내리기도 전에 "이 사람 뭐 하는 사람인지" 파악이 안 되면 그냥 닫힌다. 그래서 최신 상태 유지 + 스캔 가능성이 핵심이라는 원칙 아래 계속 다듬고 있음.

이번에 건드린 건 프로젝트 섹션 구조였다. 핵심 프로젝트 두 개는 상단에 카드로 바로 노출하고, 나머지는 토글 안으로 접어서 "관심 있으면 펼쳐봐라"는 식으로 정리했다. 보는 사람 입장에서 생각하면, 처음 방문한 사람이 프로젝트 카드를 6개 한꺼번에 마주하면 어디부터 봐야 할지 모른다. 2개만 노출하면 시선이 자연스럽게 집중된다.

<details> 토글로 구조화하는 방법

GitHub 마크다운 렌더러는 HTML 서브셋을 지원한다. <details> + <summary> 조합이 그 중 하나고, 별도 JS 없이 순수 마크다운 파일에서 접기/펴기가 된다.

<details>
<summary>More Projects</summary>

<br>

| 프로젝트 | 설명 | 스택 |
|---------|------|------|
| project-a | 한 줄 설명 | TypeScript, Next.js |
| project-b | 한 줄 설명 | Python, FastAPI |

</details>

주의할 점이 몇 가지 있다. <summary> 바로 다음 줄에 마크다운 표나 리스트를 쓰면 렌더링이 깨지는 경우가 있어서, <br> 한 줄 넣어주는 게 안전하다. 그리고 <details> 블록 안에서 코드 펜스(``)가 안 닫히는 버그가 가끔 있으니, 토글 안에 코드 블록을 넣을 때는 실제로 GitHub에서 렌더 결과를 확인해야 한다.

뱃지 얘기도 해두면, shields.io나 skillicons.dev 같은 서비스로 기술 스택 뱃지를 꾸미는 게 유행처럼 퍼졌는데, 많이 넣을수록 오히려 산만해진다. 핵심 스택 5-7개 정도, 자주 쓰는 것만. 쓰지도 않는 언어 뱃지 잔뜩 깔아두면 오히려 신뢰도가 내려가는 느낌이다.

README 작성 기준

아래 표는 지금 내가 프로필 구성할 때 쓰는 체크리스트 정도의 기준이다.

수치 기반이 제일 중요하다고 생각하는데, "성능을 개선했습니다"와 "145배 빠르게 줄였습니다"는 읽히는 무게가 완전히 다르다. 물론 수치가 없는 프로젝트도 있고 억지로 붙이면 이상하니까, 있는 것만 구체적으로 쓰는 방향이 맞다. 없는 수치를 지어내는 건 최악이고.

개발자 프로필에서 자주 보이는 실수 중 하나가 "모든 것을 다 보여주려는" 패턴이다. 사용해본 언어 전부, 참여한 프로젝트 전부, 배운 기술 전부. 근데 정보가 많을수록 핵심이 묻힌다. 이번에 토글 구조로 정리한 이유도 그거다. 관심 없으면 안 봐도 되고, 궁금하면 펼치면 된다.

트레이드오프도 있다. 토글 안에 숨긴 정보는 기본적으로 보이지 않으니, 정말 보여주고 싶은 건 토글 밖에 있어야 한다. 무엇을 앞에 노출할지 결정하는 게 사실 이번 작업에서 가장 오래 걸린 부분이었다. 두 번째 row에 어떤 프로젝트를 배치할지, 그게 접혀도 괜찮은 프로젝트인지 판단하는 게 기술적인 작업보다 훨씬 고민이 많았음.

프로필은 코드베이스랑 비슷한 면이 있다. 한 번 잘 짜두면 유지보수가 쉽고, 방치하면 점점 레거시가 쌓인다. 주요 프로젝트가 바뀔 때마다 같이 업데이트하는 걸 습관화하는 게 중요한 것 같아서, 이번에 구조를 다듬으면서 다음번에 손댈 때 덜 번거롭게 만들어두는 것도 신경 썼다.