Skip to content

Instantly share code, notes, and snippets.

View yeogue's full-sized avatar

soobin yeogue

View GitHub Profile
@yeogue
yeogue / 기술 문서를 쓸 때 주의해야 할 몇 가지.md
Created August 24, 2017 08:47 — forked from 9beach/기술 문서를 쓸 때 주의해야 할 몇 가지.md
기술 문서를 쓸 때 주의해야 할 몇 가지를 나열합니다.

기술 문서를 쓸 때 주의해야 할 몇 가지

텍스트 파일의 장점

자신이 하는 일이 소모적인 일회성의 일이 아니라고 여긴다면 위키에 글을 작성해서 보편적인 방식으로 공유하라. 글을 읽고 의문이 생기는 것에 대한 토론은 글 안에서 이루어지는 것이 좋다. 중요한 정보를 위키 혹은 RCS, 깃Git 등으로 관리되는 텍스트가 아닌, 워드, 파워포인트 등의 이진 문서로 작성해서 올릴 때마다 당신의 동료는 그 정보에 대한 접근성, 가시성, 버전 관리 문제로 고통을 겪을 것이다.

명징한 소재

잡다한 소재가 하나의 글에 다 들어가 있으면 재활용성, 접근성, 발전 가능성이 떨어진다. 자기완결적인 항목들로 페이지를 나눔으로써 정보로서의 가치가 더 커진다. 나중에 나눌 의향으로 일단 쓰고 보는 것은 환영한다. 고민 하면서 글쓰기를 미루는 것보다는 일단 쓰는 것이 중요하다.

[공통] 마크다운 markdown 작성법

1. 마크다운에 관하여

1.1. 마크다운이란?

**Markdown**은 텍스트 기반의 마크업언어로 2004년 존그루버에 의해 만들어졌으며 쉽게 쓰고 읽을 수 있으며 HTML로 변환이 가능하다. 특수기호와 문자를 이용한 매우 간단한 구조의 문법을 사용하여 웹에서도 보다 빠르게 컨텐츠를 작성하고 보다 직관적으로 인식할 수 있다. 마크다운이 최근 각광받기 시작한 이유는 깃헙(https://github.com) 덕분이다. 깃헙의 저장소Repository에 관한 정보를 기록하는 README.md는 깃헙을 사용하는 사람이라면 누구나 가장 먼저 접하게 되는 마크다운 문서였다. 마크다운을 통해서 설치방법, 소스코드 설명, 이슈 등을 간단하게 기록하고 가독성을 높일 수 있다는 강점이 부각되면서 점점 여러 곳으로 퍼져가게 된다.

1.2. 마크다운의 장-단점

1.2.1. 장점