GitHub 프로필을 토글 구조로 개선해 첫인상 가독성 높이기

GitHub 프로필 README를 꽤 오랫동안 방치해두다가 이번에 전면 개편했다. 핵심은 모든 섹션을 <details> 토글 구조로 전환한 것. 바꾸고 나서 보니 왜 진작 안 했나 싶었다.

계기는 단순했다. 채용 담당자나 협업 상대가 내 프로필을 처음 봤을 때 5초 안에 어떤 개발자인지 파악할 수 있는지를 직접 테스트해봤는데, 솔직히 답이 "아니오"였다. 스크롤을 한참 내려야 뭔가 나오고, 기술 스택 목록은 끝이 없고, 배지는 쌓여 있고. 정작 핵심이 어디 있는지 모르는 구조였다.

GitHub 프로필은 포트폴리오 사이트나 이력서보다 먼저 열리는 경우가 많다. 이름으로 검색하면 자동으로 뜨는 첫 번째 결과인 경우도 있고, 오픈소스 기여나 커밋 이력을 확인하다가 자연스럽게 프로필로 넘어오기도 한다. 그 첫 화면에서 어수선하면 그냥 탭을 닫는다. 채용 담당자 입장에서 생각해보면 당연한 행동이다. 검토해야 할 후보가 한두 명이 아닐 텐데 첫 화면에서 파악이 안 되면 시간을 더 쓸 이유가 없다.

토글 구조를 선택한 이유

핵심 아이디어는 계층적 정보 공개다. 처음 화면에는 최소한의 정보만 보여주고, 더 알고 싶은 사람이 스스로 펼쳐보게 만드는 방식. UX 맥락에서 "점진적 노출(progressive disclosure)"이라고 부르는 패턴인데, 모든 정보를 한 화면에 때려 박으면 인지 부하가 높아지고 방문자는 어디서부터 읽어야 할지 모른다. 반대로 필요한 사람이 원하는 깊이까지 탐색할 수 있게 열어두면 정보량을 포기하지 않으면서 첫인상은 깔끔하게 유지된다.

GitHub 렌더러가 HTML 서브셋을 지원하기 때문에 <details>/<summary> 태그를 마크다운 파일 안에 그냥 쓸 수 있다. 별도 플러그인이나 외부 렌더링 없이 네이티브로 작동한다는 점이 좋고, 구조 자체도 단순하다.

<details>
<summary>경력 상세 보기</summary>

### 주요 프로젝트

- 프로젝트 A: API 응답 17.8s → 0.12s (145배 개선)
- 빌드 파이프라인 재설계로 배포 소요 시간 단축

</details>

한 가지 주의할 점이 있는데, <details> 블록 안에 마크다운을 넣을 때 <summary> 태그 바로 다음에 빈 줄을 반드시 넣어야 내부 마크다운이 정상 렌더링된다. 이 빈 줄이 없으면 내부 텍스트가 마크다운이 아니라 HTML 텍스트로 그대로 출력되거나 들여쓰기가 깨진다. 처음에 이걸 몰라서 꽤 헤맸다.

README를 잡는 기준

리팩토링하면서 스스로 세운 원칙은 이렇다.

특히 수치 기반 성과 표현은 개발자 프로필에서 가장 차별화가 되는 요소다. "대용량 트래픽 처리 경험 있음"보다 구체적인 수치가 붙은 문장이 훨씬 설득력 있다. 채용 담당자가 기술 스택을 직접 깊게 파악하기 어렵다는 걸 감안하면, 결과물 중심으로 서술하는 편이 효과적이다. 추상적인 표현은 읽은 뒤에 기억에 남지 않는다.

기술 배지는 5-7개 선에서 정리했다. 보유 기술을 다 올리고 싶은 욕구가 생기는데, 배지가 20개가 넘어가면 그냥 장식처럼 보인다. 실제로 지금 현업에서 깊게 쓰는 스택 위주로 솎아냈고, 과거에 잠깐 썼거나 토이 프로젝트 수준으로만 다뤄본 기술은 뺐다. 없으면 밋밋하고 너무 많으면 산만하다는 기준으로 균형을 잡는 게 결국 시각적 밀도 조절이다.

카드 배치도 마찬가지인데, GitHub stats 카드를 쓴다면 모바일에서 어떻게 보이는지도 확인하는 게 좋다. 카드 두 개를 나란히 놓으면 모바일 뷰에서 겹치거나 한쪽이 잘리는 경우가 있다. GitHub 프로필을 모바일로 보는 사람이 생각보다 많다.

하고 나서 드는 생각

README도 코드처럼 주기적으로 리팩토링이 필요하다. 한 번 써두고 방치하면 오래된 정보가 쌓이고, 어느 순간부터는 없는 게 낫다 싶은 상태가 된다. 링크가 죽어 있거나, 예전 프로젝트를 현재인 것처럼 적어두거나, 기술 스택 목록이 지금 실제로 쓰는 것과 다르거나 하면 신뢰도가 급격히 낮아진다. 방치된 README는 관리 안 되는 문서와 같은 인상을 준다.

토글 구조의 트레이드오프도 없는 건 아니다. 접혀 있는 내용은 검색 엔진이나 프리뷰 스니펫에 잘 잡히지 않는다. GitHub 프로필 자체가 SEO를 목적으로 운용되는 건 아니니까 실질적인 문제는 거의 없지만, 그래도 핵심 키워드와 요약 문구는 토글 바깥 상단부에 반드시 노출되게 배치하는 편이 낫다. 접기 전 화면이 실질적인 "랜딩 페이지"이기 때문에.

결국 GitHub 프로필은 내가 어떤 개발자인지를 텍스트 한 화면으로 먼저 전달하는 문서다. 코드를 보여주기 전에 글이 먼저 읽힌다. 그 글이 산만하거나 묵은 정보로 가득하면 코드까지 들여다볼 이유가 줄어든다. 계속 다듬는 게 맞다고 생각한다.