[참고] GitHub Guide - Documenting your projects on GitHub
[참고] GitHub Guide - Mastering Markdown
[참고] GitHub Docs - Writing on GitHub
[참고] 위키백과 - 리드미
OS : Windows10 64bit
README 란
-
다른 사용자가 작업에 대해 자세히 알아볼 수 있는 빠르고 간단한 문서이다. 쉽게 말해 README ≒ 메뉴얼이다.
-
해당 소프트웨어(프로그램)에 대한 정보(ex. 사용법, 저작권 프로젝트에 대한 설명 등)들을 기입해놓은 문서 파일이며, 일반적으로 컴퓨터 소프트웨어와 함께 배포된다.
-
README 파일은 본인, 팀, 사용자를 위해 존재하며 필요한 정보만 포함되어야 한다. 즉, 가시성과 가독성을 고려해야 한다.
-
작성 방법은 사람마다 프로젝트마다 다르기에 정규화된 규칙은 없지만 큰 틀은 존재할 수 있다.
-
내가 작성한 프로젝트일지라도 기간이 지나면 어떤 목적으로 이 프로그램을 개발하였는지 기억하지 못할 확률이 높아진다. README 파일은 이런 불상사를 막기 위함이다.
-
README 파일이 작성되어있지 않을 경우에 개발자들이 사용하지 않을 확률이 매우 높다.
수많은 자유 소프트웨어 패키지의 소스 코드 배포판은 일반적으로 다음과 같은 표준 집합의 README 파일들을 포함한다.
| README | 일반 정보 |
| AUTHORS | 제작 정보 |
| THANKS | 도와주신 분들에 대한 정보 |
| ChangeLog | 프로그래머들이 참고할 수 있는 자세한 변경 사항의 기록 |
| NEWS | 사용자들이 참고할 수 있는 기본적인 체인지로그 |
| INSTALL | 설치 안내 |
| COPYING / LICENSE | 저작권 및 사용권 정보 |
| BUGS | 알려진 버그 및 새로운 버그 보고 방법 안내 |
README 구조
-
프로젝트 이름 : 해당 프로젝트가 어떤 프로젝트인지 소개. README 파일을 만들 때 포함된다.
-
설명 : 프로젝트에 대한 설명으로 명확하고 짧고 요점만 설명하여 작성한다.
-
목차 : 내용이 길 경우 README를 빠르게 탐색.
-
설치 : Getting Started 또는 Installation. 다른 사용자에게 프로젝트를 로컬로 설치하는 방법을 알려준다. 이미지로 명시하면 쉽게 이해시킬 수 있다.
-
사용법 : 다른 사람들이 프로젝트를 설치한 후 사용 방법을 알려준다.
-
기여 : 다른 개발자가 코드에 contribute 하기 쉽도록 설명하는 부분으로 일종의 개발 가이드라인이다.
-
크레딧 : 오픈 소스 프로젝트를 사용해 만들었거나, 누군가로부터 큰 도움을 받았거나, 크게 기여한 사람 등 프로젝트 작성자를 강조하고 링크하기 위한 것. 영화의 엔딩 크레딧이라고 생각하면 편하다.
-
라이센스 : 프로젝트에 대한 라이센스. 라이센스 선택에 대한 자세한 내용은 GitHub의 라이센스 가이드를 참조!
Markdown이란
-
GitHub에서 README 파일은 주로 .md(or .markdown) 파일 확장자로 작성한다.
-
Markdown은 웹에서 텍스트 스타일을 지정하는 방법이다. README 파일이나 온라인 문서, 혹은 일반 텍스트 편집기로 문서 양식을 편집할 때 쓰인다.
-
Markdown이 최근 각광받기 시작한 이유는 GitHub 덕분이다. GitHub의 저장소Repository에 관한 정보를 기록하는 README.md는 GitHub을 사용하는 사람이라면 누구나 가장 먼저 접하게 되는 Markdown 문서였다.
Markdown의 장단점
장점
-
간결하다.
-
별도의 도구없이 작성가능하다.
-
다양한 형태로 변환이 가능하다.
-
텍스트(Text)로 저장되기 때문에 용량이 적어 보관이 용이하다.
-
텍스트 파일이기 때문에 버전 관리 시스템을 이용하여 변경이력을 관리할 수 있다.
-
지원하는 프로그램과 플랫폼이 다양하다.
단점
-
표준이 없다.
-
표준이 없기 때문에 도구에 따라서 변환방식이나 생성물이 다르다.
-
모든 HTML 마크업을 대신하지 못한다.
README(Markdown) 작성법
GitHub - rink0123/How-to-write-by-Markdown
추천 에디터
-
-
어디서나 접속 가능하다.
-
Git에 접속하여 배포 없이 바로 Markdown의 수정이 가능하다.
-
가끔 GitHub에서 직접 commit 시 안되는 경우 사용하면 잘된다.
-
-
-
구글 드라이브, Git, 텀블러 전부 저장 및 배포 가능하다.
-
어느 PC에서 접속해도 동시성이 보장된다.
-
예쁜 Icon부터 논문 수식까지 거의 모든 Markdown 표현이 가능하다.
-
마무리
"README ≒ 메뉴얼" 이라고 생각하면 편할 듯하다.
솔직히 README 구조는 어떻게 작성하든 작성자 자유지만 본인, 팀 또는 다른 사용자에게 해당 프로젝트에 관한 설명이나 사용법은 반드시 명시해야 후에 혼란이 발생되지 않는다고 생각한다.
Markdown은 웹 에디터에서 도구 모음들이 있어 힘들진 않지만 모든 것을 제공하는 것이 아니기에 기본 상식은 알고 사용하는 것이 좋다.