DanzzaN

프로젝트 README는 오래 유지될 설명과 원천 문서의 입구로 구성한다

주장

프로젝트 README는 목적·해결하려는 문제·구조·선택 이유처럼 오래 유지될 설명과 상세 원천으로 가는 입구를 중심으로 구성한다. 현재 상태·버전·비용·진행률처럼 자주 변하는 정보는 담당 원천으로 연결해 여러 문서를 함께 갱신하는 부담을 줄인다.

이는 DanzzaN이 Second Brain README를 구성하며 채택하고, 앞으로 프로젝트를 생성할 때 재사용하기를 요청한 작성 선호다.

적용

  • 처음 읽는 사람이 무엇을 위한 프로젝트인지, 주요 구성은 어떤 역할인지 이해할 수 있게 설명한다.
  • 안정적인 설명을 뒷받침하는 설계·결정·근거 문서를 연결한다. 세부 설명은 해당 원천이 소유한다.
  • 운영 상태·구현 범위·버전·비용·최근 검증 결과·진행률·다음 작업은 운영 기록, Current, Issue 등 실제 담당 원천에서 확인하게 한다.
  • 사용·실행 안내는 프로젝트 이용에 필요한 만큼 제공하고 상세 절차는 담당 문서로 연결한다.
  • README에 정리한 설명을 이후 사이트의 프로젝트 소개·설계·운영 글을 작성할 때 출발점으로 활용할 수 있게 한다.
  • 목차와 설명의 깊이는 프로젝트의 성격과 독자에 맞춰 조정한다.

적용 경계

  • 고정 목차나 모든 README의 최소·최대 길이를 정한 선호가 아니다.
  • 갱신 부담을 줄인다는 이유로 프로젝트 이용에 꼭 필요한 안내를 생략하지 않는다.
  • 목적·구조가 바뀌거나 연결된 원천이 이동하면 README도 맞춘다. 갱신할 필요가 전혀 없다는 뜻은 아니다.
  • README의 설명을 사이트에 그대로 복사하거나, 비공개 기록을 공개하기로 한 결정은 아니다. 공개할 내용과 독자별 설명은 해당 작업에서 정한다.
  • 기록된 선호가 실제 갱신 시간을 줄였다는 측정 결과를 뜻하지는 않는다.

근거와 연결

그래프 뷰

백링크