웹매뉴얼 만드는 방법

출처: 텍스트리 – 테크니컬 커뮤니케이션 서비스 전문 기업 (textree.co.kr)

웹 매뉴얼은 모바일 퍼스트 시대에 선택이 아닌 필수적인 요소 입니다.
많은 기업들이 제품 매뉴얼을 제공하는데 있어 제품에 인쇄용으로 제공하는 매뉴얼을 온라인 고객센터에서 PDF 문서의 형식으로 제공하는 것이 일상적이었습니다.

물론 아직 이조차도 제공하지 않고 있는 기업들도 있긴 합니다.~

웹 매뉴얼이 아닌 온라인 고객센터에서 제공하는 PDF 제품 매뉴얼이 바로 가기 링크 및 검색 등으로 인해 좋긴 하지만 모바일 퍼스트 시대에서는 그 한계점이 명확하게 드러납니다.

인쇄용 문서를 모바일 화면에서 보기란 너무나 불편합니다.

 

 

아래 기업의 매뉴얼을 한번 보시겠습니까?

이미지를 클릭하시면 ‘WH-1000XM2’의 웹 매뉴얼을 보실 수 있습니다.

 

이렇게 소비자 중심의 매뉴얼 제작을 위한 여러 방법 중 오늘은 텍스트리 콘텐츠 제작팀 테크니컬 라이터의 글을 통해 웹 매뉴얼을 제작하는 방식을 알려드릴까 합니다.

 

1. 웹서비스를위한 매뉴얼 
   전자 상거래를 비롯한 많은 웹 서비스들이 있습니다. 어느 웹 서비스의 이용 방법에 대한 설명이 PDF 문서를 통해 제공된다면 대부분의 사용자들이 불편을 느낄 것입이다. PDF 파일을 내려받고 그것을 읽기 위해 PDF 뷰어를 띄우는 것은 보통 소비자들에게 여간 불편한 일이 아닐 수 없습니다.
   특히 웹 서비스에서 사용자 인터페이스와 기능들의 빈번한 변경은 자연스러운 일입니다. 많은 사람들은 웹 서비스의 변경에 따라 매뉴얼 역시 실시간으로 반영되리라 생각합니다. 그것이 우리가 HTML 매뉴얼이라 하지 않고 웹 매뉴얼이라 일컫는 까닭이기도 합니다.

 

 

1. HTML 매뉴얼을어떻게만들 것인가?
   매뉴얼을 작성하는 사람의 입장에서 HTML 포맷은 그다지 달갑지 않은 일입니다. 워드 프로세서 같은 문서 도구들은 PDF뿐만 아니라 HTML로도 저장하는 기능을 제공하지만, 그 기능을 사용하는 사람들은 많지 않습니다. 가장 큰 이유는 HTML 파일 하나가 여러 페이지들로 이루어질 수 없다는 것입니다. 100 페이지 짜리 문서를 HTML 파일 하나로 만들 수는 없는 노릇이죠.
   그로 인해 내용을 여러 파일에 나누어 담고 그것들이 서로 연결되게 하는 작업은 불가피할 수밖에 없습니다. 고지식한 사람이라면 HTML과 CSS의 문법을 익혀서 직접 작성할 것입니다.

 

<a href=”#menu” class=”link_direct”>메뉴</a>
<img src=”image/logo.svg” width=”40″ height=”20″ alt=”MySite”>

 

 

1. 마크다운이란?
   마크다운(Markdown) 은 경량 마크업 언어입니다. 위에서 예로 든 HTML 코드가 마크다운에서는 이렇게 표현됩니다.

 

[메뉴](#menu) 

 

HTML 문서를 웹 브라우저가 아닌 텍스트 에디터로 보면, 아주 많은 유형의 HTML 태그들이 있어서 실제 내용을 읽어내기가 쉽지 않습니다. 이에 반해 마크다운의 마크업은 아주 단순하여 태그로 보이지 않습니다. 그래서 내용을 읽고 이해하는 데에 전혀 어려움이 없습니다. (https://namu.wiki/w/마크다운 페이지를 참조.) 마크다운을 사용하기로 결정했다면 다음 질문은 HTML 파일을 얻기 위해 무슨 마크다운 소프트웨어를 사용하느냐입니다. 상당히 많은 마크다운 편집기 또는 변환기들이 있습니다.

 

 

그 많은 방법들 가운데 깃허브와 지킬이 이번 포스팅에서 소개하려는 것입니다.

1. 깃허브와지킬
   깃허브(GitHub)는 웹 기반 버전 관리 저장소입니다. 아주 많은 사람들이 자신들이 개발한 소프트웨어나 폰트를 공유하기 위해 깃허브를 이용하고 있습니다. 깃허브는 또한 호스팅 서비스도 제공합니다. 자신만의 독특한 블로그를 만들고 싶은 사용자가 해야 할 일은 HTML 파일을 만들어서 자신의 저장소에 올리는 것뿐입니다. 여전히 HTML 문서를 만드는 것 자체가 난제로 보이지만 깃허브 사용자들은 이 문제에서 자유로운 편입니다. (지킬 (Jekyll) 때문이죠)
   지킬은 깃허브에서 작동하는 사이트 생성기입니다. 마크다운 파일을 깃허브에 올리면 지킬이 즉각 그것을 HTML로 변환합니다. 지킬을 내 저장소에 설치하는 방법은 아주 간단합니다. 지킬 깃허브 페이지에서 오른쪽 상단에 있는 Fork를 클릭하면 지킬이 내 저장소에 복사됩니다.

 

지킬을 사용자의 로컬 컴퓨터에 설치하는 것도 가능하다. 지킬이 사용자 컴퓨터에 설치되어 있을 때 웹 문서들을 만드는 과정이 다음과 같습니다.

1. 텍스트 에디터를 이용하여 마크다운 문서를 작성한다. 마크다운 문서를 저장할 때마다 지킬이 HTML로 변환한다. 
2. 생성된 HTML 문서에 오류가 없는지 확인한다. 
3. 깃허브 데스크톱 같은 프로그램을 이용하여 마크다운 파일을 깃허브에 올린다.

 

 

1. 지킬테마
   HTML 문서의 페이지 레이아웃을 달리하고 싶다면 CSS를 비롯한 템플릿 파일들을 손봐야 합니다. 제목의 크기나 색을 바꾸는 것 이상을 기대한다면 이 일은 쉽지 않습니다. 하지만 고민할 필요 없습니다. 세상은 넓고 친절한 지킬 사용자들은 많습니다. ^^
   많은 지킬 테마들이 (http://jekyllthemes.org/)에서 제공되고 있습니다. 생각하고 있는 것에 가장 가까운 테마를 내려받아 설치하고 다른 테마들을 참조하여 템플릿 파일들을 수정하면 원하는 것을 어렵지 않게 구현할 수 있을 것입니다.

 

누가 지킬을 사용하는가? 
많은 사람들이 블로그를 목적으로 지킬을 사용하고 있습니다.( https://github.com/jekyll/jekyll/wiki/Sites에서 지킬을 이용하여 만들어진 많은 사이트들을 볼 수 있습니다.) 이 글의 주제인 웹 매뉴얼은 어떠할까요? 지킬이 웹 매뉴얼을 만들기에도 좋은 수단이라고 말할 수 있을까요? 실제 사례를 바탕으로 말씀드리겠습니다.

 

가비는 웹 기반 포스 (POS) 서비스입니다. 가비 사용자들은 안드로이드 기반의 포스 앱을 사용하여 주문과 결제를 처리합니다. 모든 거래 정보는 가비 서버에 저장됩니다. 가비 사용자들을 위한 웹 매뉴얼 (https://wisefour.github.io/gabe-manual/) 이 지킬로 만들어졌습니다.

 

지킬로 만들어진 가비 웹 매뉴얼

 

필자는 테크니컬 라이터로서 가비 매뉴얼 개발 프로젝트에 참여했습니다. 지킬 설정에서 겪는 약간의 시행착오를 제외하면, 가비의 관리 사이트와 앱을 이해하고 그에 대한 글을 작성하는 데에 주어진 시간의 대부분을 사용했습니다. 출판의 관점에서 HTML 문서 제작은 PDF에 비해 많은 기술적 문제들을 야기합니다. 이를테면, 이미지 파일들을 비롯한 많은 부수 파일들이 HTML 파일에 딸려 있는데, 그것들을 위한 디렉터리들을 어떻게 배치하느냐도 중요한 문제입니다. 그에 따라 이미지 파일이나 상호 참조의 경로가 달라지며 디렉터리 구조 문제는 번역할 때 두드러집니다. 언어에 관계없이 공통으로 사용될 수 있는 파일들이 있는가 하면 그렇지 않은 것들이 있기 때문입니다. 그런 기술적 문제들에 대해 최종 결정을 내리기까지 여러 시도들이 불가피하게 되풀이됩니다. 지킬 덕에 우리는 페이지 디자인에 투입되는 시간을 크게 줄이고 양질의 내용을 만드는 데에 집중할 수 있었습니다.

 

6 정리하면… 
HTML 파일 각각은 독립된 문서이지만, 총체적 문서가 되려면 한 그룹 안에서 조직되어야 합니다. 조직되어 있지 않다면 HTML 파일들은 종잡을 수 없는 정보의 파편들에 불과하겠죠? HTML 문서의 맹점이 그 조직화가 용이하지 않다는 데에 있으며 전통적인 조직화 방법은 상당한 수고를 요구합니다. 대안 중의 하나가 XML 소프트웨어였습니다. 그러나 그것들은 소규모의 문서화에서는 너무나 값비싼, 품도 적지 않게 드는 솔루션입니다. 필자가 주목하는 것은 지킬보다는 마크다운입니다. 변환기가 없다면 마크다운은 쓸모없지만, 마크다운의 극도로 제한된 문법 (syntax)이 글 쓰는 이들을 타이포그래피의 강박에서 해방시켜줍니다. 마크다운은 텍스트로만 채워진 지극히 전통적인 글쓰기를 강요합니다. 그렇게 할 수밖에 없습니다. 저자나 독자나, 꾸밈보다는 내용에 집중하게 하는 것, 그것이 마크다운의 미덕이 아닐까요?

 

글 작성 : 글로벌 콘텐츠팀 Hugh

2017-11-11 12:00 AM