그것은 가치가 있거나 심지어를 추가하는 데 필요한 추가 정보 파일에서 모든 새로운 프로젝트입니다. 오늘 우리에 초점을 맞출 것이 좋은 사례의 쓰기와 같은 파일과 함께 몇 가지 예가 및 준비 템플릿을 사용할 수 있습니다.
README 파일이란 무엇입니까?
README(이름에서 알 수 있듯이:”read me”)는 새 프로젝트를 시작할 때 읽어야하는 첫 번째 파일입니다. 그것은 프로젝트에 대한 유용한 정보의 집합이며 일종의 매뉴얼입니다. README 텍스트 파일은 많은 다양한 장소에 나타나며 프로그래밍뿐만 아니라 참조합니다., 그래도 프로그래머의 README 에 중점을 둘 것입니다.
의 예 추가 정보에 대한 부트스트랩을 보석(Ruby On Rails)
추가 README 파일 GitHub 에서 나타나 아래 목록에서 파일을 저장소.
우리가 전문적으로 일하거나 코딩을 배우면 여러 번 공개 저장소를 접하게됩니다. 우리가 사용하는 라이브러리를 사용할 수 있는 다른 개발자들로는 오픈 소스 코드나 우리는 우리의하여 프로젝트,보고서/고정,버그를 추가하는 새로운 기능., 그들은 단지 편리하기 때문에 확실히,우리는 이러한 프로젝트를 사용하고,높은 품질의 솔루션을 제공합니다. 그러나 사용자 친화적 인 설명,즉 좋은 추가 정보가 부족한 경우이를 사용하겠습니까?
나머지입니다-당신을 알게 느낌의 실망을 찾을 때 잠재적으로 해결할 수 있는 방법은 모든 문제의 라이브러리에서 또는 프로젝트 설명은 가난하고,쓸모 또는 사용할 수 없습니다.
좋은 README 를 작성하는 데 어떤 용도가 있습니까?
이미 짐작할 수 있다고 생각합니다., 좋은 추가 정보는 다른 사람에 대한 이해를 우리의 코드를 포함,그리고 왜 그것은 주목할 만하다. README 파일은 github 에서뿐만 아니라 브라우저(예:Google)에서도 프로젝트를 다시 작성하는 데 필수적입니다.
방금 배우고 있는데 왜 README 파일을 추가하는 것에 대해 귀찮게해야합니까? 그 코드는 결국 나를위한 것이지 전체 커뮤니티를위한 것이 아닙니다.나는 코드가 단지 당신을위한 것임을 의심한다. 그리고 README 파일을 추가하는 것은 좋은 움직임입니다.,
주니어 Devs 에 대한 README
좋아,이제 우리가 첫 번째 프로젝트 이후 우리의 README 파일에 대한 관심을해야하는 이유를 확인하자!
코드가 단지 당신을위한 것이더라도,아마도 당신은 잠시 후에 다시 돌아올 것입니다. 좋은 추가 정보할 수 있는 다시 시작하기 위해 프로젝트-시간을 낭비하지 않고에서 리콜:무엇이었을까?
신진 프로그래머의 경우 GitHub 는 전화 카드입니다. GitHub 의 프로젝트는 대부분 우리의 포트폴리오입니다., 우리가에서는 경력 단계없이는 상당한 상업적 체험 또는 멋있는 비영리 프로젝트,프레젠테이션의 업적의 형태로 저장소 중 하나입의 최선의 방법은 보이 모집. 인터뷰 중에 과시하고 싶은 몇 가지 시범 프로젝트를 준비하는 것이 가장 효과적입니다.
면 우리는 그냥 우리는 우리의 훈련 프로젝트가자의 주의하는 그들의 좋은 설명이 있습니다., 심지어 비기술적인 모집할 수 있을 인식하는 기술을 우리는 감동,그리고 확인하는 경우에 후보자의 프로필은 그/그녀의 찾고 있습니다.
폴란드어 또는 영어로?
확실히,영어로. 프로젝트가 폴란드어로되어 있어도 영어로 프로젝트 설명을 추가하십시오. 대학에서 실현 된 프로젝트는 종종 폴란드어로 문서를 요구하기 때문에 exeption 으로 취급 될 수 있습니다. 다른 모든 경우에는 영어로 프로젝트를 설명하십시오.
README.md -잠깐,그게 다 뭐야?,
.md확장은 단어에서 온다:마크 다운. 텍스트 서식 지정을위한 마크 업 언어입니다. 어쩌면 처음에는 분명하지 않지만 텍스트 작성을 쉽게하기 위해 마크 업이 만들어졌습니다. HTML 언어에서 가장 중요한 제목은h1태그와 함께 사용됩니다. 이와 유사하게 문서의 제목 앞에#가 있습니다.
텍스트 또는 코드 편집기(메모장,Sublime,Atom,CS 등)에서.md파일을 편집합니다.).github 및 dillinger 에서 markdown 사용에 대한 자세한 내용을 확인할 수 있습니다.,io 당신은 미리보기와 편집기를 찾을 수 있습니다.
좋은 README 작성-newbies 매뉴얼
Open a README.md.새 프로젝트에 파일.,
파일이 있는지 확인하십시오 항상 포함하는 다음 요소:
- 제목과 내부 제목
- 소개-프로젝트의 목표
- 기술
- 실행
고려도를 사용하여 추가적인 요소와 같은:
- 내용의 테이블
- 림
- 범위의 기능
- 의 예를 사용하여
- 프로젝트 상태
- 원
- 기타 정보
That’s a lot! 내 프로젝트에 대해 할 말이 많지 않습니다!,
거기에-하지만 당신은 이미 그 사실을 모르고 있습니다.
제목과 내부 타이틀
제목을 설명해야 한 것을 명확하게 우리가 여기고,그것은 일반적으로 프로젝트의 이름-H1 제목 앞에
#. 프로젝트의 이름이 그 내용을 공개하지 않는다면,여전히 그것이 무엇인지 제안 할 가치가 있습니다.
또한,텍스트를 포함해야 하는 제목의 섹션에서,그리고 필요한 경우-내부 제목입니다. 우리의 README 를 일관성있게 유지하기 위해 다른 모든 문서에서 유사하게 작성합니다. 우리의 README 에서.,md 파일 제목은 아래로 작성해야로 여러 개의
## header H1
## header H2
### header H3
#### header H4
##### header H5
###### header H6소개
소개 같이 요약입니다. 우리가 프로젝트에 대한 에세이를 읽고 싶지 않은 한 너무 길어서는 안됩니다. 우리는 프로젝트 목표가 무엇인지,그리고 주어진 응용 프로그램이 어떤 문제를 해결하는지 흥미로운 방식으로 설명해야합니다. 작은 프로젝트의 경우 두세 문장으로 충분합니다.교육 프로젝트 인 경우 인센티브를 언급하십시오. 왜 그것을 만들고 싶습니까? 특정 기술을 배우려면? 해커 톤 프로젝트 였나요?, 비영리 단체를위한 것입니까? 워크샵이나 온라인 코스에서 자료를 암기하기 위해 만든 응용 프로그램입니까? 의심의 여지없이 여기에서 언급할만한 가치가 있습니다.
기술
우리가 사용한 언어,라이브러리 및 버전을 적어 보겠습니다.
예를 들어,
- 스트랩 3 4
- 련 1.6/각도 2+/4/5/6
- PHP5 7
- Python2.7 또는 3.6
- 레일 4 또는 5
왜? 첫째,미래에 프로젝트를 시작할 때 도움이 될 것입니다., 이 라이브러리 버전의 변경,그리고 눈에 띄지 않는 변경을 많은 문제가 발생할 수 있습니다. 우리 코드가 우리가 원하는 방식으로 정확하게 작동 할 때 사용 된 버전을 아는 것이 좋습니다.
또 다른 것:모집. IT 채용 담당자는 후보자의 GitHub 계정을 탐색합니다. 비록 그들이 부족한 기술적 지식을 추정한 품질의 솔루션을 그들이 알고 있는 키워드 관련된 자신의 일을 제공합니다. 사용 된 기술에 대한 설명은 다른 후보자들 사이에서 당신을 돋보이게 할 수도 있습니다.,
인턴쉽을위한 후보자가 많으며 채용 시간이 제한되어 있다고 가정 해 봅시다. CVs 가 선정되었으며,두 명의 유사한 후보자와 달력에 마지막으로 사용 가능한 날짜가 있습니다. 후보자의 GitHub 계정에는 동일한 수의 프로젝트가 포함됩니다. 그 중 하나는 모든 프로젝트에서 기술을 언급합니다. 두 번째 후보자는 추가 정보 파일을 추가하지 않거나 그/그녀의 프로젝트가 잘못 설명됩니다. 어떤 후보자가 인터뷰에 초대 될 것이라고 생각하십니까?프로젝트를 실행하려면 어떻게해야합니까? 프로젝트에 최소 하드웨어 요구 사항이 있습니까?,
우리는 이전에 라이브러리와 그 버전을 언급했습니다. 필요한 경우 기술,시작 및 하드웨어 요구 사항을 함께 병합 할 수 있습니다. 그러나 우리가 그것을 두 개의 하위 섹션으로 나누면,여기에 특별히 프로젝트를 시작하는 데 집중할 가치가 있습니다. 때 우리는 웹사이트 또는 응용 프로그램,그것은 관심을 설정하는 지역 환경에 대한 링크를 GitHub 페이지 또는 배포되는 응용 프로그램에만큼의 계정을 관리. 입력 데이터가 필요합니까? 그렇다면,어떤 형식으로?우리의 README 를 향상시킬 수있는 다른 요소에 초점을 맞추자.,
목차
목차는 광범위한 문서의 경우에 편리합니다. 그것은 제목에 대한 링크와 함께 간단한 목록으로 작동 할 수 있습니다.
처럼 보이는 것입니다.
그림
GitHub 할 수 있습에 대한 그래픽 README. 기술 문서는 예쁘지 만 읽기 쉽고 이해할 필요는 없습니다. 삽화는 필요하지 않습니다-그럼에도 불구하고 그들은 우리 프로젝트에 미적 가치를 부여 할 수 있습니다. 응용 프로그램의 로고,다이어그램,구성표,예시적인 스크린 샷을 표시 할 수 있습니다., 어쩌면 그림 설명서가 당신이 원하는 것입니까?리포지토리에 파일을 만들고 거기에 이미지를 추가하십시오. 파일 경로를 사용하여 다음을 사용하여 표시합니다.
!(ścieżka/do/pliku). 사용할 수 있습니다 이미지를 넘어에서 당신은 저장소하는 경우 그들은 공개적으을 사용할 수 있습니다-하지만이 항상 위험의 소유자가 이러한 원본을 삭제하는 것에서 그들은 그/그녀의 도메인 및 그들은 사라질 것이 당신의 문서에서:!(url grafiki)예:내 README 파일을 원하는 장소 블록 스키마는 것을 설명하는 방법을 알고리즘을 작동합니다., 내 스키마를 유지합니다.이미지라는 디렉토리에 jpg 파일. 를 표시하는 그것에 내 문서,내가 사용하는 코드:
!(./images/schema.jpg)범위의 기능
없는 항상에서 사용하는 범위의 기능입니다. 웹 사이트 방문 카드 또는 할 일 유형의 간단한 응용 프로그램의 경우 기능 목록은 초과 양식입니다.,
On the other hand,겉으로는 간단한 프로젝트하는 등록 확장할 수 있는 많은 흥미로운 옵션에 우리의 자랑이 될 수 있습:사용자 등록,기록 및 분류하는 작업에 따르면 날짜를 추가 주석 작업 또는 데이터 내보내기 파일이 있습니다.
의 예를 사용하여
의 경우에는 재사용할 수 있는 코드 또는 당신의 자신의 라이브러리 제공하는 설명하는 방법을 사용하여 우리의 프로젝트가 필요할 수 있습니다., 로 작동할 수 있는 조각의 코드:
## Code ExamplesTo generate lorem ipsum use special shortcode: `put-your-code-here`으로 표시됩니다:
프로젝트 상태
그것에 가치를 추가하는 프로젝트 상태는 경우에 특히 프로젝트는 아직 개발되고 있습니다. 그것이 우리 도서관이라면,계획된 변화,개발 방향 또는 우리가 개발로 끝났음을 강조하기 위해 언급합시다.
소스
프로젝트가 튜토리얼을 기반으로하거나 주어진 작업에 영감을 얻었을 때 정보를 추가해야합니까? 예,확실합니다.
나는 그 문제에 의심을 얻지 못한다., 우리가 다양한 출처에서 배우고 진행 상황을 문서화한다는 사실에 당황하는 것은 없습니다. 우리는 많은 튜토리얼을 완성하고 학습 자료를 선택합니다. 그것의 변화를 제공하지 않고-그리고 전혀 배우지 않고-생각없는 복사는 대부분 일어나지 않습니다. 우리 코드가 다른 사람의 코드를 기반으로한다면 그러한 정보를 추가해야합니다.
어쩌면 우리가 사용하는 오래된 자습서-예를 들어,우리는 응용 프로그램을 작성을 가진 레일 3 습니다. 처음부터 레일즈 5 버전에 따라 새로운 프레임 워크 메커니즘을 사용합니다. 확실히 여기서 언급할만한 가치가 있습니다.,
경우 우리의 코드만에서 영감을 또 다른 솔루션/응용 프로그램을 언급할 수 있다고 쓰는 방법으로 당신이 있어서 영감을,어떤 변화를 만든,어떤 기능이 개발되었습니다.
우리가 연습 세트를 풀 때,다른 사람들이 그들의 설명을 찾을 수있는 곳을 추가 할 가치가 있습니다. 우리가이 근원에 돌아오고 싶을 경우에,연결은 쉽게 올 것이다. 이 방법으로 저자는 자신의 지식은,보낸 그/그녀의 시간을 준비하고 공유 이 재질은 또한 존경합니다.,
기타 정보
정보에는 저자,연락처,www 및 소셜 미디어 링크,라이센스의 유형에 코드를 사용할 수 있는 방법에 대한 정보에 기여하는 프로젝트 이들은 예의 무엇을 할 수 있는 프로젝트에 추가됩니다.
좋은 읽기 읽기
위의 제안은 내 것입니다. 가장 중요한 점은 가독성 일뿐입니다. 철저한 문서 작성으로 리포지토리가 채용 담당자 및 다른 프로그래머 앞에서 빛을 발합니다. 좋은 읽어보기를 작성하는 데는 많은 접근법이 있습니다., 을 살펴의 예는 다음과 같
- 노드-로 간단한 설명,의 스크린 샷을 응용의 예를 사용하여
- 웹 애플리케이션–화려한 예 설명의 제공을 위한 방문 페이지 유형의 웹 사이트를 사용하여 응용 프로그램 API 를 사용합니다. 설명 작동 방법,screenshots,기술영업 이 솔루션에서 추가적인 정보에 기능을 구현할
- Pomolectron–우리는 로고,스크린샷,명령에서 설치 및 설명을 작동 방법
- Git 점 모범적인 안드로이드 프로그램입니다., 테이블의 콘텐츠 네비게이션을 쉽게,screenshots,언급된 기능,그리고 정보를 어떻게 지원하는 응용 프로그램의 개발
추가 정보 템플릿
나를 떠나 당신은 여기에는 예 README.md 파일 템플릿 당신은 다운로드 할 수 있습니다. 그 서식을 살펴보고,당신의 원시 버전을 복사 README.md 파일.
이 문서에서도 사용할 수 있에 폴란드 Flynerd.pl 블로그입니다.
