훌륭한 GitHub 자술서 작성 방법

나는 내가 읽을 수 있는 최초의 자술문건find을 통독했다.1975년에는 UIC CS 부문의 윌리엄 J. 얼이 썼다.이 글은 약간 무미건조하지만 놀랍게도 44년 뒤였다.컴파일러에 오류가 있어서 이 함수를 정확하게 컴파일할 수 없습니다.
읽어보기 파일은 저장소의 유지 관리 방식을 반영합니다.좋은 프로젝트가 반드시 활발하고 결함이 없고 완벽한 테스트를 의미하는 것은 아니다.그러나 이것은 소유자가 당신, 사용자, 또는 미래의 관리자에게 관심을 가지고 있음을 나타낸다.좋은 자술은 프로젝트 사용과 프로젝트 참여에 필요한 모든 것을 알려줄 것이다.그것은 프로젝트를 판매하지만 방문객의 시간을 존중하여 그들이 다른 해결 방안을 필요로 하는지 알 수 있도록 한다.
GitHub 프로필을 응용 프로그램의 일부로 사용할 때, 자술 파일은 다른 한편으로는 매우 중요하다.그들은 좋은 의사소통 능력과 소프트웨어 관련 문서를 작성하는 기술을 보여 주었다.누군가가 당신의 코드에 깊이 들어가 추상적인 프로젝트 해석을 제공하지 않기를 바랍니다. 이것은 상당히 큰 요구입니다.

선명한 묘사
누군가가 코드를 한 줄 읽지 않아도 너의 소프트웨어를 사용할 수 있을 것이다.
우선 GitHub에서 제공하는 기본 제목을 python-ml-project-for-cat-lovers-2으로 변경합니다.다음 단계는 가장 간단한 형식으로 당신의 프로젝트를 설명하는 것입니다.많은 사람들이 맨 끝에 패드를 사용한다.

A bot that downloads and indexes Cat GIFs

잠재적 고객 설명에 더 많은 내용을 추가함에 따라 인지적 과부하의 가능성을 증가시켰다.언어를 아래로 편집한 후, 제목, 줄 바꾸기, 간격을 사용하여 언어를 더욱 분리합니다.(두 줄의 신조어는 새로운 단락을 나타내고 Cat Crawler - Classify Cat GIFs는 휴식을 나타낸다.Cheatsheet .) 제품 표지와 스크린 캡처를 회피하지 마라.다른 기술 문서와 달리 멀티미디어는 이곳에서 양호하게 나타난다.더욱 심오한 저장소에 배경 읽기 부분이 도움이 될 것입니다.
만약 당신의 저장소가 매우 재미있거나 가볍고 유쾌하다면, 당신의 설명은 이 점을 나타낼 것입니다.Strunk & White자리는 있지만 인터넷도 쿨한 프로그래머들의 모임이다.not-paid에 고객이 비용을 지불하지 않으면 사이트가 어느 날 보이지 않을 때까지 서서히 퇴색될 것이라고 외친다.

사용법
어떤 사람이 당신의 프로젝트를 어떻게 사용합니까?만약 그것이 API라면 가장 기본적인 상호작용 코드가 있을 것이다.전체 문서는 페이지 아래나 다른 위치에서 찾을 수 있습니다.facebook/react 한 예로 그것들의 사용법을 보여 주었다. 한 사람이 사용할 수 있는 가장 작은 방식이다.단일 체크 부호 인용 코드를 사용하고 새 줄에 세 개의 체크 부호 인용 코드 블록을 사용합니다.언어를 처음 세 개의 체크 표시줄 뒤에 놓아서 특정한 강조 표시를 합니다.

function HelloMessage({ name }) {
  return <div>Hello {name}</div>;
}

ReactDOM.render(
  <HelloMessage name="Taylor" />,
  document.getElementById('container')
);

이 상호작용의 출력을 표시합니다.GIF를 어떤 식으로든 사용할 수 있다면 그렇게 하세요!GIF는 대량의 데이터를 독자의 머릿속에 전송하는 인류에게 해석하기 쉽다.alexfoxy/laxxx는 매끄러운 인터넷 애니메이션 라이브러리로 이 점을 완벽하게 실현할 수 있다.

오픈 소스 툴ShareX을 사용하여 GIF를 만듭니다.화면에서 한 영역만 선택하면 됩니다.내가 추천한 또 다른 소스 오픈 솔루션은LICEcap이다.

설치하다.
항목이 실행되는 것을 보고 방문자가 설치하기를 원합니다.이 절은 때때로 제목이'입문'이다.항목마다 이것만 있어야 한다<br>.정적 사이트라면 이렇게 말해라!npm install catcrawler . 기본 도구를 이해한다고 가정해 보세요.host the parent dir on a webserver나 pip가 무엇인지 설명할 필요는 없지만, 새 설정에서 실행되는 모든 명령을 보여 주어야 합니다.
어떻게 구축하고 운행하는지 설명하는 완전한 장과 절이 있다. 쉽게 접근할 수 있도록 하려면 좋은 모델이다.가상 머신을 시작하고 설치 가이드를 복제하는 것은 아주 좋은 방법입니다. 이 작업을 완성하기 위해 자동 구축 테스트를 하지 않았다고 가정하십시오.

배지

깃허브 배지는 주로badges/shields 표준화돼 방문객이 아래로 굴러갈 때 처음 보는 일이다.구축 상태 휘장 설명 항목의 안정성.다른 배지에는 저장소의 활동과 월별 제출 횟수, 또는 관리자의 수가 표시될 수 있습니다.그것들은 강제적이지는 않지만 GIF와 비슷해서 거대한 상금이다.
shields.io에는 자신의 휘장을 만드는 데 사용되는 API가 있고 사용하기 쉬운 npmpackage이 있다.몇 주 전에 나는 그것을 들고 휘장을 몇 개 들고 한 시간도 안 되어 뛰어 들어갔다.또 다른npm 대체 방안은badger이다.파이톤pybadges은 구글이 발표했다.
만약 당신이 첫 번째npm 배지를 얻고 싶다면, DEV에 글을 써서 GitHub에 지속적인 통합을 시작하도록 안내합니다.

이바지
만약 당신이 그들을 찾고 있다면, 공헌자가 사용할 수 있는 부분은 매우 도움이 되고 환영받을 것이다.루트 디렉토리에 파일을 추가하는 데 사용되는 GitHubstandard가 있습니다.이것은 행위 준칙과 문제를 찾고 요청을 구축하는 일반적인 준칙을 포함할 수 있다.많은 초보자들은 개원 프로젝트를 돕는 과정에 대해 초조해하며 한 걸음 한 걸음 그들을 이끌면 그 중의 일부 문제를 완화시킬 수 있다.만약 당신이 어디서부터 시작했는지 확실하지 않다면, 나는 최근에 행위 준칙 generator 을 보았는데, 나는 그것이 상당히 깔끔하다고 생각한다.내 친구들은 관리자의 상호작용을 위해 엄격한 지도 원칙과 규칙을 갖춘 저장소만 지원한다는 것을 안다.

라이선스
내가 업무 중에 해결 방안을 찾을 때, 허가증은 내가 먼저 찾아야 한다.GitHub을 통해 저장소를 만들 때 라이센스를 선택하면 해당 라이센스에 대한 파일build: passed이 생성됩니다.GitHub은 이 파일에 page의 이름이 하나 더 있습니다. 그들은 choosealicense.com의 창작자입니다. 이것은 아주 좋은 안내서로 모든 옵션을 조회할 수 있습니다.나는 개인적으로 마성이공대학의 소스 코드를 사용한다.어떤 사람들은 허가에 대해 강한 견해를 가지고 있는데, 특히 GPL 관련되었을 때."GPL 또는 소프트웨어에 대한 수정 사항은 (컴파일러를 통해) GPL 허가 코드를 포함하여 GPL 아래에서 제공해야 하며, GPL 아래에서 설명을 생성하고 설치해야 한다."

거푸집
Therearemany자술 템플릿.그것들은 중요한 고비에서 매우 좋지만, 나는 비교적 작은 항목이 이런 상자에 잘 들어가지 못하기 때문에 발생하는 텍스트가 약간 냉담하다는 것을 발견했다.성숙한 프로젝트는 템플릿에서 더 많은 이익을 얻을 수 있지만 개발자가 소프트웨어에 투입될 수 있는 시간을 고려하여 맞춤형 해결 방안을 가지는 것은 가치가 있다.
This는 내가 가장 좋아하는 것이다. 왜냐하면 그것은 단도직입적이고 테스트에 관한 두 개의 소절이 있기 때문이다.만약 네가 어떤 테스트가 있다면, 이것은 너의 자술에서 언급해야 한다.복제 프로젝트를 실행할 때, 테스트를 실행하는 것은 내가 설정이 개발할 준비가 되어 있음을 확보하는 첫 번째 일이다.

기타 부분
일단 네가 모든 중요한 장과 절을 다 보았다면, 자술한 내용을 가득 채워라.나는 소수일 수도 있지만, 나는 GitHub을 훑어보고 새로운 것을 찾고, 그것들이 어떻게 구축되었는지 발견하는 것을 좋아한다.나는 많은 예시 코드의 상세한 저장소를 매우 좋아한다.나에게 있어서 하나의 프로젝트에 참여하는 데 중요한 것은 관리자가 적어도 나와 같은 관심을 가지도록 확보하는 것이다.
탐색 trending 당신의 프로그래밍 언어를 탐색하고 표준 레이아웃을 이해합니다.영감을 얻으려면 제가 최근에 가장 좋아하는 두 종류Gatsyby와 lax.js를 보세요.가장 중요한 것은 당신의 문서를 부르게 하는 것입니다.
150여 명을 가입하여 저의 newsletter 프로그램과 개인 성장을 등록하세요!
나는 트위터에서 과학 기술에 대해 이야기했다.