개발자가 알아야 할 모든 측면을 포함해야 하며, 개발자가 직접 받을 수 없는 것은 코드. 여기에는 개발 시 해야 할 일과 하지 말아야 할 일, 전체 배포 지침, 외부 통합 설명 등이 포함됩니다. 이 게시물에서는 강력하고 아름답고 가독성이 뛰어난 README 파일을 만드는 방법을 안내합니다. 프로젝트.

잘 준비된 프로젝트 문서에 대한 좋은 소개는 깃허브 가이드에서 확인할 수 있습니다: https://guides.github.com/features/wikis/. 여기에는 "README는 개발자가 프로젝트를 사용하고 기여하는 데 필요한 정보만 포함해야 한다"고 명시되어 있습니다.

이를 염두에 두고 Codest에서 프로젝트 문서를 작성할 때 따르는 구성 요소와 모범 사례 목록을 소개합니다.

빠른 소개

- 프로젝트 제목모든 README의 필수 항목입니다.

- 상태 배지외부 코드 품질 측정, 자동화된 테스트 또는 기타 도구를 사용하는 경우 문서의 시작 부분에 해당 도구가 작동하는지 다른 사람들에게 보여줄 수 있는 좋은 장소입니다.

- 설명프로젝트에 대한 몇 문장을 추가하여 프로젝트의 주요 목적과 기능을 빠르게 설명하세요.

목차

내용 목록은 긴 문서 파일에 유용할 수 있지만 README가 매우 간결하다면 필요하지 않습니다.

일반 정보

- 정보 섹션프로젝트에 대한 자세한 설명으로 사용자, 역할, 좀 더 혼란스러운 사례, 스크린샷 등을 포함할 수 있습니다.

- 목업UI/UX 목업 리소스가 있는 경우 해당 리소스에 대한 링크가 있는 곳입니다.

• 다음과 같은 기타 정보 서버 액세스 또는 외부 API와의 통합예를 들어 스테이징 인스턴스 URL 주소, 민감하지 않은(!) 공유 액세스 자격 증명, 문서 링크, 일부 지침 등이 있습니다.

설치

- 요구 사항애플리케이션 설정을 시작하기 전에 충족해야 하는 전제 조건(예: 외부 도구 설치).

- 설정프로젝트를 시작하고 실행하기 위해 따라야 할 단계별 지침입니다.

- 설정로컬 설정이 저장되는 위치를 설명하고 사용자 고유의 설정을 받는 방법에 대한 지침을 제공합니다.

- 로컬 구성로컬 설정에 대한 몇 가지 사례가 있는 경우 설명하기에 좋은 곳입니다.

개발

이 섹션은 기능 개발, 버그 수정, 핫픽스, 공통 기능, 테스트, 스타일 가이드, 코드 정리, 프로젝트에 사용되는 기타 개발 도구(예: 가드 또는 도커) 등과 같은 지침을 위한 이상적인 장소입니다. 모든 규칙을 언급하는 것을 잊지 마세요. 팀 회원이 알아야 할 사항입니다.

배포

각 환경에 대한 명확한 단계별 지침과 배포를 진행하는 동안 '알아두면 좋은' 모든 정보를 제공합니다.

별도의 섹션을 위한 기타 아이디어

- API 문서

- 변경 로그

- 외부 리소스도움이 될 만한 모든 종류의 링크가 있는 곳입니다.

- 애플리케이션 스택프로젝트에서 사용하는 애플리케이션 스택 목록 - 간단한 설명과 공급자의 이름을 포함할 수 있습니다.

팀

현재 프로젝트 팀원을 표시할 필요가 있는지 여부는 논란의 여지가 있지만(깃허브는 기본적으로 전체 기여자 목록을 제공합니다), 프로젝트의 작성자 중 한 명으로 이름이 표시되면 항상 좋습니다. 이 경우 가능한 한 최신 상태로 유지하세요.

마지막으로 몇 마디

기억하세요: 각 프로젝트는 고유하며 문서도 마찬가지입니다. README를 작성하는 데 있어 하나의 훌륭한 솔루션은 없습니다. 일반적인 팁을 따르되, 가장 중요한 것은 리팩터링에 대해 항상 기억하는 것이며, 이는 README와도 연결됩니다. 항상 문서 전체를 살펴보고 다른 방식으로 표시해야 할 부분이 있으면 다시 생각해 보는 것이 좋습니다.

한 가지 더: '지침'이 핵심이므로 많이 작성하세요. 감사합니다!

자세히 읽어보세요:

• 개방형-폐쇄형 원칙. 꼭 사용해야 하나요?
• 좋은 품질의 코드를 작성하는 방법은 무엇인가요?
• Vuelendar. Vue.js를 기반으로 하는 새로운 코데스트의 프로젝트