기술블로그 글쓰기에 대해서
들어가기
지금까지 4주간 document기준으로 20개가 넘는 글을 썻다.
이제 글쓰기라는 행위 자체에 대한 부담감이 많이 줄어들었다.
그냥 쓰기에서 잘 쓰기 로 넘어가기 위해 고민들을 공유하려고 합니다.
비슷한 고민중이시라면 읽고 댓글…. 써주시면 좋죠
이 글은 블로그를 운영하면서 계속 업데이트 됩니다.
0. 읽기
글쓰기 자체를 시작하기전 단계라서 0번에 넣었다.
좋은 글을 쓰려면 가장 먼제 해야하는 것은 좋은 글을 읽는 것이다.
사실 좋은 글을 찾아내는 것도 쉽지 쉽지 않고 읽기도 쓰기만큼 힘들다.
하지만 좋은 글을 많이 읽어야 좋은 글을 쓸 수 있다
1. 완성된 글
좋은 블로그 기본요소는 좋은 컨텐츠 이다.
좋은 컨텐츠라고 정의하는 요소는 매우 복합적이다 뛰어난 필력, 기술적 정확성, 등등…
그중에서도 정보전달 이 기술블로그가 추구해야하는 좋은 컨텐츠 라고 생각한다.
정보전달을 잘하기 위해서는 온전한 문장으로 완성된 글 의 형태를 가지고 있어야한다.
온전한 문장으로 완성된 글은 노트에 끄적인 것을 그대로 올리는게 끄적인 것을 초안삼아 누구에게, 무엇을, 어떻게를 고민하며 다시 쓴 글을 뜻한다.
2. 짧은 글쓰기
처음에는 긴 글을 쓰는 것, 많은 것을 설명하고 많은 것을 보여주는게 멋진 것이라고 생각했었지만 긴글은 쓰는 사람도 읽는 사람도 긴 호읍이 필요하다.
특히 모니터로 글을 읽을 떄 나를 포함 많은 분들이 긴 호흡의 끝까지 집중해서 보지 못한다.
즉 정보 전달 이 제대로 되지 않을 가능성이 있는 것이다.
미디엄에서는 영어 1,000자당 1분, 한글 500자당 1분 정도라고 하고 독자들이 가장 많이 끄는 글은 7분 정도 분량이라는 분석이 있다.
읽는 사람이 한호흡으로 읽을 수 있도록 최대 길이를 7분(5,600자)분량이 되도록 줄이는 노력을 해야겠다.
2.1 글을 나누는 것에 대해
튜토리얼 같이 긴글를 너무 인위적으로 7분을 맞출 필요는 없다.
독자가 마음을 먹고 긴호흡으로 읽어야 하는 글은 그대로 긴글로 만드는 것이 더 좋을 수 있다.
튜토리얼 같은 경우 앞에서 작은 실수가 다음글에서 문제로 발생하는 경우도 있는데 그럴 경우 읽는 사람은 해당글에서 원인을 찾다 튜토리얼을 포기하기도 한다.
2.2 글의 분량
4000 ~ 10,000 자 정도가 독자의 흥미도 SEO 관점에도 이상적은 분량이다.
그치만 쓰려는 글에 따라서 적절한 분량을 조절하면 된다.
3. 글의 형식
Daniele Procida씨의 아무도 알려주지 않는 문서화의 비밀에서 소프트웨어 문서 형식에는 튜토리얼, 하우투 가이드, 설명, 레퍼런스 4가지로 분류합니다.
저의 경우 레퍼런스를 제외한 3가지가 짬뽕처럼 섞여서 ‘가이드'라는 이름을 달고 나왔었다.
짬뽕이 맛있게 만들 수 있다면 상관없지만 글이 이도 저도 아니게 되기에 각 특성에 맞게 나만의 형식을 정하려고 한다.
3.1 공통
어떤 글을 쓰더라도 상단에 # 들어가기를 꼭 서야겠다.
해당 포스팅의 의도(목적)과 이 글을 읽을 떄 이런걸 주의 해줬으면 좋겠다 등등..
독자로써 이 글이 읽을만한 글이라는 것을 어필하는 단계라고 생각하면 된다
3.2 튜토리얼
튜토리얼 같은 경우 독자가 원하는 것은 기술을 사용해보기 일 것이다.
튜토리얼에 해당 기술의 목적(철학)과 내부적 작동 원리를 설명 보다는 ‘이 코드를 넣으니 저렇게 되네요 우와아아’ 정도만 들어가는게 맞는 거 같다.
이미 튜토리얼을 따라 코드를 작성할 정도면 그 기술에 대한 흥미와 관심이 있다고 봐도 되기 떄문이다.
굳이 장점은 뭐고.. 철학은 뭐고… 등등 이런 이야기는 튜토리얼에 앞쪽 혹은 뒤쪽에 링크를 다는게 좋다.
그리고 튜토리얼은 환경세팅이 매우매우 중요하다.
초반에 환경을 자세하게 명시해줘야한다.
# 들어가기
# 소개
튜토리얼을 따라하기전 xxx의 소
[]()
# 튜토리얼 환경
* windows 10
* JVM 8 이상
* Docker 설치
# 튜토리얼 시작
# 마치며 (선택사항)
3.3 하우투(How-to) 가이드
하우투 가이드는 전적으로 특정 문제해결 방법 에 대해서만 다뤄야 한다.
하우투 가이드에는 문제 해결이라는 목표 달성에 중심을 줘야지 개념을 설명하면 안된다
가이드를 읽는 독자가 원하는 것은 문제를 해결하는 방법을 알고 싶은 것이지 개념을 공부하러 온 것은 아니기 때문이다.
이건 알아야 한다는 개념이 있으면 이것도 링크 혹은 하단에 작성해야한다. 여지만 남겨두고 가이드 글에서는 빠져야 한다.
그리고 하우트 가이드는 하나의 글로 끝내야한다.!
방법이 아무리 길어진다고 해도 글 하나로 문제를 해결할 수 있어야 한다.
가이드는 제목을 자~알 지어야 한다.
Ex) Spring JPA에서 복합키를 사용해서 테이블 Mapping하는 방법
# 들어가기
해결하려는 문제에 대한 설명
# 해결 방법
1. 컴퓨터를 재시작한다.
2. 컴퓨터에게 소리를 질러본다.
3. 말을 안들으니 때려본다.
4. 그래도 안된다면 밥을 뻇는다. (전원을 뽑기)
# 개념(작동원리)
링크 또는 간략한 설명
3.4 설명(혹은 토론)
설명은 특정 주제에 대해서 명확하게 밝혀야 한다
설명을 듣고 싶은 독자는 이해 지향적 이며 원한다면 충분히 기술에 대해서 깊게 들어가도 된다.
설명은 코드보다는 그보다 넒은 시아를 가지고 여러 관점에서 접근 할 수 있어야 한다.
좋은 설명을 쓰기 위해서는 첫번째로 주제 선정에 있다.
주제가 명확하지 않으면 이것저것 설명하다 글 자체가 산으로 갈 수 있다.
그러지 않기 위해서 철저하게 특정한 주제만을 설명하고 필요한 사전 지식이나 그외의 내용들은 링크를 통해서 여지만 남겨야 한다.
설명을 읽는 독자는 이해가 목적이라고 했다.
독자가 주제의 사전 지식을 글 초반에 물어봐야한다.
제시한 사전 지식을 다 갖췄는데도 주제에 대해 이해시키지 못했다면 제 잘못이겠지만, 사전지식이 부족하다면 그건 책임 질 수 없다.
그리고 주제에 본문으로 들어가기전 용어 정의할 필요가 있고 글 전체에서 용어를 혼동해서 쓰지 않도록 조심해야한다.
자짓 용어 떄문에 이해를 방해 할 수 있다.
# 들어가기
# 사전 지식
SQL, JDBC에 대한 지식이 없다면 읽는데 어려움을 느낄 수 있습니다.
SQL에 대한 간략한 설명 [링크]()입니다, 먼저 읽어보시길 권장합니다.
# 용어정리
* "A" : 알파벳의 첫글자이다.
# 본문
# 마치며 (선택사항)
마무리
글쓰기는 이정도면 된거 같다.
다음에는 기술 블로그에서 글쓰기 외에 중요한 것을 알아보려고 한다.