문서화 프로젝트1 : 방향 결정하기

다음 글 : 환경설정하기

목차

1. 왜 HTML인가? 2. 문서작성의 기본 철학 3. 표, 그림/그래프, 수식 삽입방법   - 표   - 그림/그래프   - 수식

프로젝트의 목표는 다음과 같다.

1. 쉽게 내용 수정이 가능(+검색)
2. 쉽게 보관이 가능
3. 쉽게 공유가 가능(클라우드 및 웹 공유)
4. 비용이 저렴

 

왜 HTML인가?

 삼성노트는 손 필기를 지원한다. 손 필기에 대한 로망 때문에 컴퓨터 테블릿, 삼성노트 휴대폰, 갤럭시탭을 사용했었다. 결론적으로 키보드세대에게 문서 수정은 역시 타이핑이 가장 빠르다. 검색이나 수정역시 타이핑이 빠르다. 손 필기를 한 번 더 편집해야하는 재편집의 문제도 있었고, 삼성노트 모바일은 필기를 위해 훈련을 해야하는 단점이 있었다.

타이핑으로 가닥을 잡았을 때, 문제는 표와 그래프, 사진, 수식을 넣는 과정이었다. 타이핑을 유지하되 어떻게 단점을 보완해 나갈지에 대한 프로젝트가 문서화 프로젝트의 핵심이다.

사진/영상/블로그 등 쉽게 참조를 삽입하기엔 역시 txt보다는 pdf, ppt, html, ml이 우수하다. OneNote나 SamsungNote도 후보에 올렸었으나, OneNote는 레이아웃 인터페이스가 너무 까다롭고, SamsungNote는 PC를 지원하지 않는 것이 컸다. PDF는 여러어플을 끼워팔아서 그런지 에디터 하나에 월 5만원은 너무 비싸다고 생각했다. html은 배우기 어렵고, 편집기랑 뷰어를 동시에 띄워야 하는 부작용이 있다. Mark Up언어(ml)은 편집이 간단하지만 그 만큼 표현의 제약이 존재했다. 조금 학습을 하더라도 표현이 자유로운 html로 작성하기로 결론을 냈다. 최종으로 html을 선택한 이유는 진입장벽은 있지만 일단 익숙해지기만 하면 다양한 툴을 사용이 가능하고, 원하는 표현이 가능해지기 때문이었다.

또 다른 이유 중 하나는 추가 설치를 하지 않아도 된다는 점이었다. 20년 전에는 툴바가, 10년 전에는 ActiveX가, 지금은 어플이 인기다. 그러다보니 뭘 깔라고 하는데 거부반응이 있다. html은 누구나 가지고 있는 브라우저를 사용하기 때문에, 어느환경에서도 추가 설치를 하지 않아도 된다.

어플	장점	단점
SamsungNote (삼성)	필기작성이 가능함	PC환경이 좋지 않음 - PDF변환은 되지만, 편집은 지원하지 않음
OneNote (Microsoft)	클라우드 연동	편집이 불편함
Keep(Google)	웹환경이 주어지면 언제나 가능	아주 단순한 텍스트만 지원
Evernote	자체클라우드 및 타 클라우드 연동기능 (6,000/월)	어플이 없으면 열람이 안됨
PDF(Adobe)	깔끔한 표현력	너무 비쌈(50,000/월)
Hwp한글	깔끔한 표현력	옛날에 해적판은 썼지만 기업이 사는것이지 개인이 사는것이 아님. 호환이 안됨
MS-Word (Microsoft)	office365 (100,000/년) 어차피 구독함	편집이 너무 어려움. 모바일 버전은 왜 있는지 모르겠음.

 

html을 작성할 때, 에디터와 뷰어를 동시에 띄워야 하는 이유가 "글자 색을 바꿈", "그림을 삽입 함"과 같은 메타데이터를 함께 작성해야 하기 때문인데, 블로그는 하나의 에디터에서 작성과 피드백이 동시에 된다는 점이 좋다. 후술하겠지만 메모장, notepad++, vscode와 같은 툴을 이용해서 작성하고 apache나 IIS, git과 같은 툴을 이용해서 피드백을 받는 방법도 이미 어느정도 진행되었다. 우선은 블로그를 이용한 방법에 대해서 언급하자면:

html을 가장 쉽게 사용하는 방법은 블로그이다. 창을 하나만 띄우면 되기 때문이다. 우리나라는 크게 Tistory와 네이버블로그를 사용할 수 있는데, 사실 다른 옵션으로 깃블로그도 사용할 수 있다. 셋 다 이용해봤는데, 네이버가 접근성이 좋아서 현재 꾸준히 100명 이상 들어오고 있다. 꾸준히 하루 20명 정도 열람되는 문서의 경우 꼬박 1주일 동안 매달렸었다. 자고 일어나서 자료조사만 하고 자고 일어나는 것을 반복해서 말이다.(돈을 벌려고 했던 건 아니었다.) 만약 이슈를 다루면 하루 동안 작성 할 수도 있지만 약 한 달정도 100~200명이 방문하는 정도이다. 생각해보자. 네이버가 양질의 컨텐츠를 만들어서 마진이 남는다면 그 사람을 정직원으로 고용해서 작성하겠지, 하청을 주겠는가? 결론은 블로그로 돈을 벌자라는 생각은 애초에 접는 것이 좋다는 생각이다. 다만, 블로그로 돈을 벌 생각이 아니라고해서 블로그에 있는 well-made 에디터를 버릴 이유가 있을까?
(덧, 인터넷엔 장사꾼들이 너무 많다. 광고배너 다는 사람들을 비판하는 것이 아니다. 정직하지 않고 정보를 왜곡하려는 부류들을 비판하고 싶다. 뒷광고와 조회수 늘리기 꼼수는 비난 받아야 한다.)

블로그	특징
네이버 블로그	편집기가 잘 만들어져 있다. 분석이 편하다. 검색이 잘 된다. 할 수 있는게 거의 없다. 특: 누군가 자꾸 쓰레기를 버리고 감
Tistory	편집기가 모드별로 지원된다. HTML모드로 사용하면 다양한 기능을 사용할 수 있다.
깃블로그	알아서 해야한다. 제약이 없다.

 

 

문서 작성의 기본 철학

 대화/글의 목적이 수신자의 정보수집이라면 작성도 당연히 수신자를 기준으로 해야 한다. 이 단락은 그런 고민에 대한 반평생의 고민이다. 좋은 글이란 잘 읽히는 글이다. 다시말해, ①자연스럽고 ②어렵지 않아야 한다. 긴 글을 작성하면서 언급한 두 가지 조건을 지키기가 매우 어려워진다. 따라서, 기호와 표, 그래프를 적극 활용해야 하는 이유가 여기에 있다. 

 그럼에도 불구하고 글을 남겨야 하는 경우 두 기준에 대해 부연 설명을 하자면:
 먼저, 자연스럽다는 것은 흐름이 일정하다는 것을 말한다. 우리 생각은 군더더기가 많다. 그리고 순서가 없다. 비약도 있다. 때문에 완벽한 문장으로 작성되는 것이 10이라면 7~8은 (어쩌면 그 이상을) 지워버린다. 자연스러운 글을 만들기 위해 가장 중요하고 어려웠던 작업은 불필요한 말을 삭제하는 작업이었다.
 둘째, 어렵지 않은 글이란 의외로 호흡이 짧은 글이다. 문장이 길어지면 쉬운 문장도 어려워진다. 그래서 다음 작업은 긴 문장을 짧게 자르는 작업이 된다. (잘라지지 않는다면, 쉼표를 적극적으로 활용해야 한다.) 그 다음 단어를 살펴본다. 어려운 단어란, 수준이 높은 것이 아니고, 잘 사용되지 않기 때문임을 알아야 한다.

 결론적으로 긴 글은 작성하기는 하지만 잘 읽지 않는다. 지켜야 할 것도 많고, 열심히 퇴고를 했다고 해도, 한달 두달 일년 십년 뒤에 보면 아쉽다. 이 글도 그러할 것이다.(성경도 한 번에 읽고 이해 안되는 부분이 있지 않나?) 아이러니하게 긴 글은 화자에게 도움이 된다. 글로 작성하다보면 생각이 정리된다. 그 만큼 생각에는 군더더기가 많고, 서로 대립된다. 때문에 내 말이 누군가에게 설득력이 있으려면 글로 작성해보는 것이 좋다. 요새 인터넷 기사, 계약서, 심지어는 법(법제처에서 열람이 가능)도 기본 철학이 없이 작성되고 있다. 아쉬운 부분이다.

문서 표현 철학
표, 그래프, 그림으로 표현하기	Best
글로 표현하기	자연스럽게 쓰기	불필요한 문장 제거, 문장 순서
	쉽게 쓰기	호흡을 짧게, 고어/사어 교체

 

 

표, 그림/그래프, 수식 삽입 방법

태그tag를 사용해야 한다. 태그는 <>로 둘러쌓여 있고, 작성은 되지만 직접 보여주지는 않는다. 태그 안에는 예약된 단어를 정해진 순서대로 작성하면 된다. 옵션으로 사이즈와 위치, 색, 동작 등을 작성 할 수 있는데, 가끔은 올바르게 작성되었음에도 불구하고 브라우저 이슈(+버전 이슈)로 동작하지 않는 경우가 드물게 있어서 시간이 크게 낭비되는 경우가 종종 있다. 기능은 Javascript로 디자인은 css로 이전을 했기 때문에 옛날에 비해서 html 작성시간이 많이 단축되었다. 따라서 html에는 내용만 담는다.

표	태그사용[or 블로그툴], 스프레드시트 인용, 파일업로드
그림/그래프	서버개설(후술) 후 태그사용[or 블로그툴], 스프레드시트 인용
수식	DeX사용(mathjax스크립트)

 

표

html에서는 <table>테그를 사용하고 가로는 <tr> 세로는 <td>를 사용해서 작성 할 수 있다. 예를들어:

<table>
  <tr>
    <td> 1번
    <td> 2번
    <td> 3번
  <tr>
     <td colspan=2> colspan=2
     <td rowspan=2> rowspan=2
  <tr>
     <td> 4번
</table>

표현 예:

1번 2번 3번 colspan=2 rowspan=2 4번
결과물

색을 입히는 방법과 사이즈를 지정하는 방법은 colspan과 같이 옵션으로 width(넓이), height(높이), bgcolor(배경), border(선두께), margin(여백), padding(내부여백), align(정렬) 등으로 지정이 가능하지만, 디자인을 컨텐츠와 섞어버리기 시작하면 나중에 "편집은 할 수 있는데, 편집을 할 수 없는" 문서가 되어버리는 치명적인 단점이 되므로, 디자인 요소는 후술하는 css에 남겨두도록 한다.

정지된 표는 이와 같이 작성해도 전혀 문제가 되지 않는다. 표가 아무리 방대해도, 마우스로 드래그하는 사람이 스킬이 없는 것이지, 엑셀에 "데이터>데이터 가져오기>웹"을 이용해서 1분도 안되서 가져올 수 있기 때문이다.

https://www.namechart.kr/ 은 대한민국 인기있는 신생아 이름을 공개하고 있는 사이트다. 표 가져오기를 연습해보자.

문제는 작성중인 데이터를 어떻게 공유하는지에 관한 내용이다.

결과물

 위 작업은 위 사이트를 엑셀로 긁어온 다음에 스프레드시트에 그대로 붙여넣기 했다. Google Doc에서는 "스프레드시트"를 무료 소프트웨어로 사용할 수 있다. 엑셀의 기능을 100% 활용 하기는 어렵지만 그런대로 수정 가능한 엑셀을 작성 할 수 있다. 게다가 클라우드에 저장된다는 점도 큰 메리트다. 물론 행렬식이라던가 아리따운 대쉬보드를 못 만드는 단점이 있다. office365엑셀에 bahttext함수가 잘못 인코딩되었다고 MS에 메일을 넣었는데도 아직도 유효한 것을 보면 업데이트를 안하는 것 같으면서도, unique함수라던가 행렬함수 등 최근에는 꽤 단순하게 작성 될 수 있는 내용이 구버전/해적판에서는 동작하고 있지 않다. 엑셀 작업을 도와주다가 구 버전이라 동작하지 않을 때는 꽤 난감하다.

• 방법1: table태그를 이용
• 방법2: 구글 스프레드시트로 작성한뒤 웹에 게시(파일>공유>웹에게시...>삽입 탭>게시)
• 방법3: 엑셀파일을 업로드

 

그래프

그래프는 <image src=url>로 가능하다. 내가 작성한 이미지가 아닌 경우에야 쉽게 긁어 올 수 있지만, 내가 올리는 경우 서버를 마련하고 이미지를 업로드 한 뒤, 업로드 주소를 불러와야 한다. 출력 예:

<image src="https://iseohyun.github.io/html/img/tangerine.jpg" width=248>

Ctrl+v로 붙여넣은 이미지
결과물

<image src="https://drive.google.com/file/d/10u0ZhbePF4GbTfRHsrvD6Aw4f7aJ1JUQ/view?usp=share_link" width=248>

 

또는 google doc의 "스프레드시트"에서 차트를 직접 작성 한 뒤 차트 공유를 통해서 차트를 공유할 수 있다.

<iframe width="600" height="371" seamless frameborder="0" scrolling="no" src="https://docs.google.com/spreadsheets/d/e/2PACX-1vR-Gy016dso70bK-2WDZK64rLtwLFhQSbGmopeqs3XENwABVi-VVjhs1XLdd5TQj2ao2ty2eoWS9k4i/pubchart?oid=1950280283&amp;format=interactive"></iframe>

결과물

※ 랜덤함수를 이용해서 그래프를 그렸기 때문에 새로고침을 할 때마다 다른 그래프를 보게 될 것이다.

 

• 방법1: image 태그를 이용한다.
  • 방법1-1: 내 서버에 게시하거나, git서버(무료)에 업로드 한 뒤 링크를 획득(서버개설방법 후술)
  • 방법1-2: 다른 사람의 그림을 도용한다.(출처표기)
  • 방법1-3: 클라우드 서버 이용하기(단점:기간제, 서버미지원 가능성)
• 방법2: 블로그 에디터를 이용한다. (장점: 서버개설이 불필요)
  • 네이버: 파일로 저장 후, 업로드 버튼을 이용한다.
  • tiStory: Ctrl+v로 업로드 가능
• 방법3: 스프레드시트를 이용해서 표를 직접 업로드

 

수식

 수식의 경우 툴을 이용해서 이미지로 옮긴 뒤에 이를 불러오는 방식을 사용할 수 있는데, 문제는 한컴서비스(https://goodbye.malangmalang.com/)는 2022년 9월 27일로 종료가 되었다.  그래프 툴인 (https://www.desmos.com)와 AI수학풀이기(https://www.wolframalpha.com/)에서 수식을 간단하게 작성하는 요령이 있어서 더 찾아본 결과 (https://docs.mathjax.org)에서 추가 설치 없이 웹에서 끌어다 쓸 수 있는 수식 편집기를 구할 수 있었다.

<!DOCTYPE html>
<html>
<head>
<title>MathJax TeX Test Page</title>
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
</script>
<script type="text/javascript" async
  src="https://example.com/mathjax/MathJax.js?config=TeX-AMS_CHTML">
</script>
</head>
<body>
When $a \ne 0$, there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
</body>
</html>

위 예제는 해당 홈페이지에서 추천하는 방법이고, 아래 방법으로도

<script src="//cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
근의 공식은 \(a \ne 0\)일때, 식 \(ax^2 + bx + c = 0\) 에 대해서...
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$

 

근의 공식은 \(a \ne 0\)일때, 식 \(ax^2 + bx + c = 0\) 에 대해서... $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$
결과물

 

• 방법1: 수식편집기를 이용 (단점:그림이라 수정/검색 안됨. 스케일 깨짐. 번거롭다.)
• 방법2: TeX 문법을 사용 (mathjax를 script로 불러온다.(초간단))

https://ko.wikipedia.org/wiki/%EC%9C%84%ED%82%A4%EB%B0%B1%EA%B3%BC:TeX_%EB%AC%B8%EB%B2%95

위키백과:TeX 문법 - 위키백과, 우리 모두의 백과사전