게으른 업데이트에 대한 핑계 글…
최근 글을 잘 쓰지 않고 있는 것에 대해 핑계(?) 삼을 글을 남긴다.
지난 3주간 악재가 너무 많았다. 집중을 분산시키는 요소로 인해 글 쓰는 것을 한동안 멈추고 있다. 악재를 몇 가지 나열해보면.. 가정에 안 좋은 일이 있었고, 내 몸 안에서 3개의 혹을 발견했으며, 부상으로 인해 축구도 못하고 있다. 게다가 키보드도 고장났다. 여러가지 불안 요소가 날 이리 저리 흔들어 놓는 바람에 최근에는 직장의 일만 처리하기도 벅찰 정도이다. 생각을 정리하기도 힘들다. 어디가서 머리 속을 비우는 시간을 가지고 싶다는 생각뿐이다. 너무 많은 양을 머리로 처리했다면 그 머리를 식혀야 하는데 요즘은 어떤 것으로도 식히지 못하고 있으니 답답하다. 남처럼 기호 식품(술, 담배)을 즐기는 편도 아니고 대중 놀이 문화 즐기는 편도 아니다. 그나마 스트레스를 풀어주던 축구(운동)도 다리의 연골판 파열로 인해 앞으로 못할 상황이다.
몸도 마음도 휴식이 필요하다. 글을 쓰며 마음을 차분히 가라앉히는 것도 좋은 방법이지만 중복 키눌림 현상을 일으키는 고장난 키보드로 이렇게 글을 쓰는데 20분 가까이 걸린다. 더 스트레스를 받는다. 그래서 몸과 마음이 재충전될 때까지 필수적인 일이 아니면 잠시 손을 놓고 쉬려한다.
DocBook XML과 Multi Channel Publishing..
이전 글에서 출판 기능 중 위키 텍스트를 DocBook XML을 만들어 내는 스크립트에 대해 이야기 했었다. 해당 스크립트를 통해 생겨나는 결과물인 DocBook XML은 그 자체만으로도 재활용 가능한 문서 포맷이지만 출판 기능에서는 독자가 원하는 다양한 문서 포맷으로 생성하는 것이 목표였다. 한글 닥북 패키지를 이용하면 RTF 문서, Compiled HTML Help 문서, PDF 문서, WebHelp 문서를 생성할 수 있고, 다른 패키지를 이용하면 ODF 포맷 문서(.odt)도 생성할 수 있다. 이 모든 것의 중심에는 DocBook XML이 있었다. 즉, 데이터와 스타일이 분리된 구조, 즉 문서 형태가 데이터와 구조로 이뤄진 방식으로 정보를 가지고 있다면 다양한 포맷으로 문서를 생산해 낼 수 있는 것이다. 위키의 출판 기능도 아래와 같은 기능을 갖추려 했다.
Multi Channel Publishing Concept
이를 위해선 출판 기능 UI 페이지에서 사용자가 요구하는 문서의 출력 형태를 입력받아야 했고 그것을 구분하여 문서를 출판해내는 스크립트를 만들어야 했다. 위에서도 설명했듯이 DocBook XML을 공용 포맷으로 사용하기 때문에 DocBook XML을 만드는 과정까지는 어떤 포맷을 출력하든 같은 과정을 거쳤다. 그리고 그 이후에는 각 포맷별로 해당 문서 포맷을 생성하도록 스크립트를 짜야했다.
Multi Channel Publishing Converting Script
PDF 포맷의 문서를 생성할 때는 다음과 같은 과정을 거쳤다.
- 위키를 DocBook XML로 변환한다(Wiki2Docbook 스크립트(가칭)).
- DocBook XML을 한글닥북이 제공하는 XSL을 사용하여 XML FO 형태로 변환한다(XSL 프로세스-xsltproc).
- XML FO 형태의 문서를 PDF로 변환한다(Apache FOP).
PDF의 문서 스타일을 바꾸기 위해 XSL 파일을 커스터마이징해야 했다. 몇번 수정하다가 생각보다 손이 많이 가는 작업이라 스타일을 많이 바꾸진 못했다. PDF 생성이 가장 오랜 시간이 걸렸다. 스크립트뿐만 아니라 xsltproc와 Java를 사용하여 문서를 변환해야 했다. 긴 시간이 걸리다보니 양이 많은 문서의 경우 문제가 발생하기도 했다. 웹에서 HTTP 요청으로 문서 생성을 수행하지만 TimeOut 시간전까지 변환을 완료하거나 진행 상태를 표시하여 연결을 유지해야 했다.
ODF 문서의 경우 docbook2odf라는 스크립트가 오픈 소스로 존재했다. 굳이 순서를 나타내면 다음과 같았다.
- 위키를 DocBook XML로 변환한다(Wiki2Docbook 스크립트(가칭)).
- DocBook XML을 ODF 문서 형태(.odt)로 변환한다(docbook2odf).
DocBook XML이 생성되면 해당 문서를 docbook2odf라는 스크립트로 변형하면 그만이었다. 그렇게 어려운 부분은 없었으나 스타일을 커스터마이징할 수 있는 범위가 제한적이었다.
그리고 WebHelp 문서의 경우 한글닥북 패키지에서는 XSL 변환으로 바로 XHTML 형식으로 문서를 생성했다.
- 위키를 DocBook XML로 변환한다(Wiki2Docbook 스크립트(가칭)).
- DocBook XML을 한글닥북이 제공하는 XSL을 사용하여 XHTML 형태로 변환한다(XSL 프로세스-xsltproc).
- XHTML 문서를 오픈 소스를 사용하여 WebHelp 문서를 생성한다(Ant 빌드 사용).
그것을 배포하는 사이트가 어디였는지 잘 생각이 안나지만 그 오픈 소스는 왼쪽에 TOC가 있는 형식의 WebHelp를 만들어주는 자바 빌드 패키지였다. 이를 이용해서 문서를 생성했으며, 특히 이 오픈 소스는 문서를 파싱하여 내부 색인을 생성하고 Javascript를 사용하여 검색이 가능하도록 만들어 주었다. 매뉴얼엔 검색 기능이 매우 중요한데 그것을 해결해주는 좋은 소스였다(나중에 기억이 나면 링크를 걸겠다.).
Multi Channel Publishing이 가능토록 하려고 많은 문제에 부딪히고 많은 것을 배웠다. 근 1년동안 프로젝트의 성과를 실질적으로 보여주는 결과물이었기 때문에 공을 들일 수 밖에 없었다. 문서 포맷에 대해 배울 수 있는 기회였다. 정말 아무것도 모르던 신입(지금도 막내지만)이던 시절 XML 변환에 대해 공부하려고 DocBook XSL: The Complete Guide 링크를 열었을 때를 잊을 수 없다. 방대한 문서의 명세 등에 질려버린 것이다. 끊임없이 공부해야 한다는 것을 알고 있었지만 그것을 확실하게 느낀 것은 그 때였다.
이 프로젝트에 대해 자세히 쓰려했지만 실제 내용을 보여주기엔 보안상의 문제도 있고해서 지금 사용하는 호스팅 업체에 위키를 설치하고 출판 기능을 추가하여 예를 보여주려 했다. 하지만 웹 호스팅 서비스에는 제약이 있어서 출판 기능을 보여주기 불가능하다. 그리고 내가 지금 중요하다고 생각하고 있는 것도 이젠 조금 달라졌다. 그래서 앞으로 블로그에 작성할 글은 문서를 작성하기 위해 고민하고 있는 정보 모델링(Information Modeling, Document Type Define, Information Design, Object Oriented Documentation Design)에 관련된 것과 Wiki를 CMS처럼 사용하기 위해 업무에 사용했던 전략을 써볼까 생각한다. 물론 중간중간에 재미있게 고민했던 문서와 관련된 문제도 이것 저것 남길 생각이다.
위키를 DocBook XML로 변환
선임과 맡은 프로젝트에서 먼저 처리하게된 업무는 미디어위키의 문법을 DocBook XML로 바꾸기 위해 기존 닥북위키를 위해 만들어졌던 변환 스크립트(Conversion Script)를 미디어위키의 문법에 맞게 바꾸는 것이었다. 그것을 위해 우리는 무엇을 어떻게 바꿔야하는지 정의할 필요가 있었다. 미디어위키의 문법을 알아야 했고 써봐야 했다. 주로 위키에 있는 정보를 소비할 뿐이었지 문서를 작성해 본 경험이 없었기 때문에 위키 문법에 대해 완벽하게 파악하기 힘들었다(문법의 변형도 많았다.). 또, 목표가 되는 DocBook XMl의 명세에 대해서도 공부했어야 했다.
우선 만들어야 했던 것은 변환 표(Conversion Table)였다. 기존의 스크립트를 이용하기 위해 먼저 미디어위키와 닥북위키의 차이를 분석해야 했다. 두 위키 문법의 차이를 분석하고 바로 DocBook XML 문법 변환을 하나하나 확인하였다. 다음은 그 때 만든 변환 표의 일부분이다.
Conversion Table
몇몇 항목을 제외하곤 문법이 달라 변환 스크립트를 대부분 수정해야 했고, 없는 항목은 새로 만들어야 했다. 스크립트 내부는 정규 표현식(Regular Expression)으로 위키 텍스트를 확인하여 DocBook XML로 변환하는 방식이었다. 전공 과목 중 컴파일러 수업에서 배웠던 분석기(Parser)가 생각났다. 블록 단위가 아닌 문법은 간단하게 처리할 수 있었다. 어휘 분석과 비슷한 개념이었기 때문에 단지 정규 표현식으로 간단히 해결할 수 있었다. 하지만 문제는 블록 개념의 문법이 등장했을 때이다. 구문 분석을 위해서는 저장소(Stack)의 개념이 있어야 했고 어휘 분석에서 발생하는 문법과 구문 분석에서 발생하는 문법 사이에 우선 순위가 필요했다. 중첩되는 구문 분석 사이에서도 고민해야 했다. 물론 닥북 위키에 적용하기 위해 만들어져 있던 스크립트는 이 부분에 대한 문제를 어느 정도 해결하고 있었다. 하지만 필요한 문법을 추가하거나 수정할수록 고려해야할 사항이 늘어났던 것이다. 복잡한 문제였지만 분석기를 좀 더 확실하게 만들기 위해 스크립트를 다시 설계하고 만들 생각은 없었다(항상 시간은 부족하다.). 따라서, 기존의 것을 어떻게든 잘 활용하도록 노력해야 했고, 변환 스크립트를 작성하고 시험하는 일을 반복했다.
변환 스크립트를 작성하면서 재미있었던 것을 몇개 들어보면 DocBook XML Section 요소의 id 속성을 어떤 값으로 만들어야 하는지, 링크는 어떻게 처리할 것인지, 이미지 태그를 어떻게 변환할 것인지 등이 있다.
id 속성의 경우 제약이 있는데 그것은 문서 내에서 식별할 수 있는 유일한 문자열이어야 한다는 것이다. 만약 A, B, C라는 페이지가 모두 '개요'라는 절을 가지고 있고, 이 3개 페이지를 묶어 오프라인 문서를 만들어야 한다면 어떨까? 절 이름을 id 속성 값으로 가져간다면 분명 '개요'라는 같은 id 값을 가진 section 요소 3개가 생길 것이고, 이는 DocBook XML DTD의 적법성(validation)을 위배하게 될 것이다. 그래서 페이지 제목과 절 이름의 합성으로 id를 만들었다.
...
<section id="A#가">
...
<section id="A#Description">
...
</section>
...
</section>
하지만 이 역시 문제가 있다. 하나의 페이지 내에서도 같은 절 이름을 가질 수 있는 것이다. API 레퍼런스 문서라면 API마다 설명하는 항목으로 Description, Parameter, Return, See Also 같은 절은 모두 동일하게 가지고 있을 것이다.
...
<section id="A#가">
...
<section id="A#Description">
...
</section>
...
</section>
...
<section id="A#나">
...
<section id="A#Description">
...
</section>
...
</section>
...
그렇다면 저장소(Stack)에 하위 절로 분석해 들어갈수록 절 이름을 저장해놓고 모두 나열해야할까? 즉, 'A'라는 페이지에 '가'라는 API 절이 있고 그 하위에 'Description' 절이 있다면 해당 Description 절의 id 속성 값을 각 제목과 절 이름의 조합으로 만들어야할까?
...
<section id="A#가#Description">
...
하지만 이것 역시 문제가 있다. 위키에서 해당 절을 참조할 때 페이지 이름과 단말 절(Terminal Section) 이름의 조합으로 링크를 걸기 때문이다. 즉 제목과 절 이름의 조합으로 id 속성 값을 유일하게 만들었다 하더라도 그것을 참조할 때 해당 식별자를 링크의 분석만으로 만들어내기 어렵다는 것이다. 실제 작업할 때 같은 페이지 내에서 같은 이름의 절이 나올 경우 나온 횟수를 더하는 방식(Counting)으로 해결했다. 이 방법은 페이지 이름과 말단 절 이름의 조합으로 id 속성을 작성하되 중복될 경우 끝에 숫자를 더하여 유일한 아이디를 만드는 방식이다.
...
<section id="A#가">
...
<section id="A#Description1">
...
</section>
...
</section>
...
<section id="A#나">
...
<section id="A#Description2">
...
</section>
...
</section>
...
사용자가 링크를 걸 때 사용 방식을 확인하여 얻은 해결책이다. 위키에서 링크를 걸 때 특정 API의 Description절로 링크를 걸 수 없는 것에 착안했다. 따라서 페이지에서 반복되는 절은 링크의 대상이 될 이유가 거의 없으며 단지 DocBook XMl의 적법성(Validation) 검사를 통과하기 위해 유일하기만 하면 되는 것이었다. 이렇게 하면 section 요소 id 속성 값을 유일하게 만들기 위해 저장소(Stack)를 만들 필요도 없었다.
그리고 링크의 경우는 위키의 페이지일 때와 오프라인 문서가 될 때 위치적 제약이 생긴다. 즉 문서의 위치가 변하면서 링크의 성질이 변화는 것을 알게 되었다. 내부 링크(Internal Link)가 오프라인 문서가 되는 페이지를 가르키고 있는지 아니면 오프라인 문서가 되지 않는 페이지를 가리키고 있는지에 따라 DocBook XML에서는 내부 링크(link)로 만들지 웹 링크(ulink)로 만들지 판단해야 했다. 이를 위해 페이지 목록을 만들어야 했다.
위와 같이 오프라인 문서가 됨에 따라 위치적 제약뿐만 아니라 문서의 크기적 제약도 발생하게 되었다. 인쇄용 문서가 됨에 따라 거의 문서 가로, 세로 크기의 제약이 없는 화면에서 크기의 제약이 있는 종이를 고려해야 했다. 그에 따라 가장 먼저 고려해야 했던 것은 이미지 크기의 재조정(resize)이었다. 이미지의 크기를 용지 크기에 따라 비례적인 방식으로 재조정해야 했으며, 절대적인 크기를 지정하여 해당 크기를 넘어가면 해당 크기에 고정되도록 만들어야 했다.
이 포스트에서 이야기한 문제 이외에도 도전을 자극하는 문제가 많았다. 지금 생각해보면 미디어위키 자체에 있는 분석기를 활용할 수 있지 않았을까 하고 생각해본다. 어쨋든 이 부분을 작업하면서 DocBook XML 명세 등 대해 많이 공부할 수 있었고 온라인 문서와 오프라인 문서의 차이를 체험할 수 있었다. 그 문제를 풀기 위해 나는 그 프로젝트에 몰입했었다. 마치 재미있는 논리 문제를 푸는 것 같았다. 그런 기회를 가질 수 있어서 좋았다.
Information Modeling과 위키
지난 글에서 위키 출판 기능의 기획에 대해 이야기했다. 그 내용 중 콘텐츠 재사용(Reuse)에 대해 이야기를 좀 더 다뤄보고자 한다. CMS에서 가장 강조하는 내용 중 하나인 콘텐츠 재사용은 콘텐츠가 모듈 단위로 잘 쪼개져 있어야 가능하다. 흔히 문서화할 내용이 있다면 그것을 잘 분석하여 내용을 나눌 필요가 있다. CMS 또는 싱글 소싱과 관련된 많은 책이 이 부분을 위해 내용을 분석하고 Information Model을 정립해야 한다고 이야기한다. 콘텐츠를 분류하고 최소 단위(granularity)를 정해 모듈화를 잘 해야만 해당 콘텐츠를 효과적으로 재사용할 수 있다고 이야기하고 있다. CMS 관련 책은 콘텐츠를 분류할 때, 일반적으로 크게 3가지 타입으로 나뉜다고 이야기한다(물론, 이 3가지 범주에서 좀 더 특수화(파생)되는 분류가 있다라고 생각한다.).
- Concept Type : 개념적인 설명을 다루는 콘텐츠이다. Overview 문서나 개념적 정의를 설명하는 콘텐츠가 이에 해당한다.
- Task/Procedure Type : 목표를 위한 행위나 절차를 설명하는 콘텐츠이다. 튜토리얼 같은 독자의 액션을 설명하는 콘텐츠가 이에 해당한다.
- Reference Type : 주로 참조의 목적으로 소비되는 콘텐츠이다. 사전과 같은 콘텐츠이다.
각 콘텐츠 타입별로 특징이 있지만 그것까지 이 글에서는 설명하지 않겠다.
위와 같이 나눠놓은 타입으로 콘텐츠를 분류하기 위해 초안 문서를 보고 분석해야 했다. 저번에도 이야기했지만 위키를 사용한 문서 작성이 오프라인 문서에서 쓰던 형태(재사용의 개념이 거의 없는 형태)로 머물지 않고 CMS에서 요구하는 Reuse와 Repurpose의 특징을 담으려고 했다.
책에 Information Modeling하는 방법에 대해 구체적인 설명은 없었지만 현재 문서를 분석하고, 분류한 다음 Reuse Map를 만드는 설명이 있었다. 선임과 콘텐츠를 분석하기 시작했으며 작성된 문서를 타입별로 구분이 가능하도록 작은 단위로 나누고 콘텐츠에 타입 분류를 주었다. 그리고 모듈화된 콘텐츠를 어떻게 재사용할지 나타내는 Reuse Map을 작성했다(이 때, 작성한 Information Model은 상황에 맞게 다시 수정하긴 했다.).
특별히 Information Modeling을 하기 위해 사용한 툴은 없었다. 그저 문서 A가 있다면 현재 작성된 문서를 절 단위로 일단 나누고 그 절의 성향을 파악하여 타입을 분류한 정도였다(시간의 압박이 있었기에 그것을 마냥 분석하고 있을 수 없었다.). 어떻게 보면 초안 문서를 보고 분석하여 문서 타입의 분류를 나누고 문서 타입 정의를 내린 꼴이니 역공학이라고 할 수도 있겠다. 그래서 그것에 맞추느라 Information Modeling의 결과물이 생각했던 것보다 깔끔하진 않았다. 처음부터 문서 타입을 분류하고 그 분류를 구조화했다면 그리고 그 문서 타입 정의(DTD)를 가지고 콘텐츠에 잘 적용했더라면 정말 좋았을 것이다. 뭐 감상은 뒤로 접어두고 그 때 작성한 Reuse Map의 예를 대충 보여주면 아래와 같다(보안상 콘텐츠를 분석한 부분은 제외한다.).
Reuse Map Sample
위와 같이 Information Model을 작성한 후 Wiki에 적용하기 위해 몇 가지 고민할 부분이 있었다. "Reuse를 어떻게 할 것인가?" 문제였다. 위키에서 콘텐츠의 재사용은 임베드 방식을 사용하면 된다. 중첩된 임베드도 2단계까지 가능해서 일단 만든 Reuse Map을 적용하는데 큰 문제가 없었다. 단지 지금 작성된 콘텐츠를 디자인한 Information Model 단위로 잘게 나눈 후 위키의 임베드 태그를 이용해 재조립(Reassembe)하면 된다. 그리고 각 콘텐츠를 재작성하면 되는 것이었다.
그러나 막상 이상향을 향해 잘 가고 있다고 생각하면 항상 현실적인 문제가 발생하듯이 이런 재사용을 오프라인 문서를 생성할 때 어떻게 매끄럽게 연결할 것인지 고민해야 했다. 임베드하거나 출판물의 구성을 위해 명시한 콘텐츠를 어떻게 구성하여 출판할 것인가? 오프라인 문서에 포함되는 콘텐츠가 오프라인 문서에 포함되지 않는 콘텐츠를 참조할 때는 어떻게 할 것인가?
전자는 Docbook XML의 외부 ENTITY 참조를 사용해서 구성 콘텐츠 또는 구성 콘텐츠가 임베드하는 다른 콘텐츠를 포함토록하고 문서에 포함된 콘텐츠가 아니라도 위키에서 내용을 가져와 임베드했다. 아래 그림은 문서 구성 콘텐츠를 임베드하는 개념이다. 오프라인으로 생성되는 최종 문서를 Book.xml 파일로 잡고 하위에 임베드 콘텐츠를 가져오도록 했다.
Embed Pages
후자는 아직 설명은 안했지만 위키 텍스트를 파싱(parsing)하는 중 다른 콘텐츠를 참조하는 문법이 등장하면 해당 콘텐츠가 생산되고 있는 문서에 포함되는지를 판단하여 내부 참조 링크를 줄 것인지 외부 웹 링크를 줄 것인지 결정하게 해야했다.
위의 이야기뿐만 아니라 콘텐츠 재사용을 위해 고민해야하는 부분은 너무 많았다. 그리고 어려웠다. 이런 콘텐츠 재사용(Reuse), Multi Format Publishing(Repurpose) 등의 개념이 문서 생산성을 높여주며, 테크니컬 라이터가 고민해야할 Document Engineering의 중요한 가치 중 하나이다. 그리고 나는 프로젝트를 진행하면서 싱글 소싱의 특징을 가지고 있는 강력한 CMS 도구를 찾으려고 노력했고 그런 도구 비슷한 것을 보기만 해도 가슴이 설렜다.
나는 요즘 Document Engineering에서 문서의 생산성을 높이는 것을 예전만큼 중요하게 생각하지 않는다. 테크니컬 라이터 또는 Information Designer가 어떤 가치를 창출하는가? 즉 테크니컬 라이터의 어떤 부분을 회사에서 가치있는 부분으로 인정받아야 하는지에 대해 고민한 적이 있다. 현재 테크니컬 라이터를 고용하고 있는 국내 기업은 대부분 문서 생산성 향상을 테크니컬 라이터에게 중요하게 요구하고 있고 또, 그것을 주로 평가하는 요소로 사용한다(그나마 다른 가치보다 정량적으로 측정하기 쉬워서가 아닐까?). 하지만 나는 최근 그런 부분보다 다른 부분을 중요하게 평가 받아야 한다고 생각하고 있다. 이 내용에 대해서는 프로젝트의 과거를 이 블로그에 남기다가 지루한 감이 있으면 써볼까한다. 이 포스트는 여기서 그만 줄인다.
위키 출판 기능의 기획..
2008년 10월쯤, 선임 테크니컬 라이터는 한 프로젝트를 맡게된다. 한 팀에서 미디어위키로 생산해 낸 문서를 재작성하는 프로젝트였다. 해당 프로젝트는 해당 팀이 관리하는 미디어위키에서 초안을 보고 워드로 작성하였으나 선임 테크니컬 라이터는 그렇게 하지 않기로 결정했다. 참고로 선임 테크니컬 라이터는 CMS와 싱글 소싱에 대해 상당히 많은 관심을 가지고 있었으며, 이번 프로젝트에 그 개념을 적용하려고 했다.
싱글 소싱, 그것을 팀내 스터디에서 공부했지만 실제로 이론 공부만하고 실습하지 않아서인지 와닿지 않았다. 물론 지금은 그렇지 않다. 싱글 소싱에는 큰 두 가지 개념인 Reuse와 Re-Purpose이 있다.
- Reuse : 콘텐츠를 모듈화하고 모듈화한 콘텐츠를 조건에 따라 재조합하는 것이다. 모듈화된 콘첸츠는 여러 조건에 따라 중복되게 조합될 수 있는데 이때 콘텐츠의 사본을 만들어내는 것이 아니라 하나의 원천 정보로 참조되는 것이다.
- Re-purpose : 콘텐츠를 모듈화하고 이를 중앙집중화한 후 필요한 형태의 포맷으로 문서를 생산해 내는 것이다.
그림으로 나타내면 아래와 같을 수 있다.
싱글 소싱 개념
위 싱글 소싱의 개념 중 위키를 다양한 포맷의 문서 형태로 출판하는 기능을 기획했었다. 이를 출판 기능이라 불렀다. 출판 기능을 간단하게 설명하면 위키 텍스트를 Docbook XML 형태로 변환하고 그것을 다시 다양한 문서 포맷으로 변환하는 기능이다.
출판 기능 개념
출판 기능은 미디어위키의 확장 기능으로 만들 예정이었다. 출판 기능이 기능 흐름은 다음과 같았다.
- 사용자는 UI 페이지에서 출판할 문서와 출력할 문서 형태를 선택한다.
- 문서 출판 버튼을 누르면 해당 문서에 포함되는 위키 페이지(위키 문법 형태)를 다운로드한다.
- 다운로드한 위키 페이지를 분석(파싱)하여 DocBook XML 형태로 데이터를 변형한다.
- DocBook XML을 DocBook StyleSheet를 사용하여 Fomatting Object로 변환한다.
- Fomatting Object 파일을 다시 스크립트를 수행하여 사용자가 선택한 포맷의 문서로 생성한다.
- 생성한 문서를 사용자가 다운로드할 수 있게 링크를 제공한다.
아래 그림은 PDF 문서를 생산할 때 출판 기능의 수행 흐름(Work Flow)이다.
출판 기능 흐름
위 기능을 만들기 위해 UI 페이지는 미디어위키 확장 기능 템플릿을 사용하여 만들어야 했고 단계별 페이지를 구성해야 했다. 그리고 위키 문법을 파악하여 DocBook XML 형태로 변환하기 위해 한글닥북 Dbwiki의 프로젝트로 만들어진 WikiToDocBook을 사용했다. 물론 미디어위키에 맞게 위키 문법 파싱을 다시 해야했다. 그 외에도 생각할 것들이 많았다. 앞으로 이 블로그에 포스팅은 이 출판 기능의 부분부분을 하나하나 해결해나가면서 얻었던 경험을 작성할 예정이다.
그나저나 월드컵이 나의 리소스를 너무 빼앗아가는 것 같다.
DocBook과 DITA에 대한 인식 변화..
이 블로그에 내가 가졌던 경험을 열심히 남기려 했지만 최근 월드컵으로 인해 퇴근하고 집에 와선 컴퓨터를 거의 켜지 않는다. 축구를 조금 좋아하는 편이라 앞으로 한 달 정도 계속 그럴 것 같다. 그래도 블로그를 그냥 나두는 것이 애정이 없어 보이는 것 같아 가볍게 글을 하나 더 써볼까 한다. 이번글은 XML 문서 형식인 DocBook과 DITA에 대한 인식이 바뀌어 가던 기억을 되살려 보고자 한다.
팀에서는 자체 세미나를 수행했다. 테크니컬 라이터가 갖춰야 할 지식 등을 공유하는 자리였다. 주로 문서(콘텐츠) 관리와 관련된 책(원서)을 읽고 정보를 공유하기 위해 발표 자료를 만들고 약속한 시간에 팀원이 모여 발표를 듣는 시간을 가졌다. 보통 세미나를 위한 시간(독서, 발표 자료 준비, 발표 및 세미나 참석)은 상당히 부담스러웠다. 아직 업무도 제대로 파악하지 못하는 풋내기였기 때문에 기초없이 이런 연구적 내용을 공부하거나 받아들이는데 서툴렀다. 그 와중에 팀에서는 XML 문서 형식인 DocBook과 DITA에 대한 세미나를 진행했다(그것이 무엇인지는 이 글에서 자세히 설명하지 않겠다.). 이 세미나를 하게된 이유는 팀내 문서의 저장 및 배포 방식에 따른 문제점으로 인해 문서 저장/관리를 위한 문서 타입을 찾는 것이었다. 콘텐츠 관리 시스템(Content Management System, 이하 CMS)이 정보를 하나의 데이터로 관리하고, 그것을 다양한 목적에 맞게 배포할 수 있게 하기 위한 최적의 문서 타입 후보가 DocBook과 DITA였던 것이다. 하지만 처음 세미나를 접했을 때 그 이야기는 나에게 뜬 구름 잡는 이야기였다. 그저 나에게 XML 이란 프로그램에서 데이터를 전송하기 위한 도구 정도였다. 그게 세미나에서 DocBook과 DITA를 처음 접했던 솔직한 느낌이었다. 그 때까진 워드로 작업하는 것만해도 바쁘던터라 귓 속에 그런 이야기가 잘 들어올리 없었다. 그리고 팀에서 XML, XSL 등 XML 포맷과 그것을 활용하기 위한 명세나 규격 등을 자세하게 알기 위해 스터디 할 때도 두 포맷(DocBook과 DITA)은 그 저 누가 정해놓은 DTD에 불과했다.
그 후 직장 선임 테크니컬 라이터와 한 프로젝트에 참여하게 된다. 그 때가 대충 2008년 9월~10월 정도 였던 것 같다. 한참 워드 문서로 작업하고 기초적인 것을 다지고 있을 때였다. 그 프로젝트는 문서를 미디어위키로 작성해야 했고, 선임 테크니컬 라이터는 미디어위키에서 문서를 다양한 포맷으로 배포할 수 있는 기능을 만들려고 했다("Multiple Purpose"는 SingleSourcing을 활용하는 기본적인 기능이다.). 해당 기능을 만들기 위해 선임 테크니컬 라이터는 기능에 대한 기획안(추후 다른 글에서 해당 내용을 작성할 것이다.)을 보여줬다. 그것은 위키 텍스트를 DocBook 형식으로 바꾸고 DocBook에서 FOP를 사용하여 다양한 형태의 포맷으로 문서를 생산하는 것이었다. 이 때 XML을 공부하면서 얻은 지식(XSLTPROC, DocBook DTD 등)을 프로젝트에 활용하면서 이 모든 것의 핵심이 왜 DocBook인가를 이해하게 된다. DocBook DTD는 이미 문서에서 정보와 스타일(포맷)을 분리하고 있었다. 이 때, 처음으로 DocBook와 DITA에 대한 인식이 크게 한번 바뀐다. 하지만 이 프로젝트에서는 DocBook만 사용하여 DITA에 대해서는 DocBook와 크게 다를 것이 없을 것이다라고 생각할 뿐 별다른 생각이 없었다.
그렇게 출판 기능(이 내용도 다른 글에서 작성할 예정이다.)을 만들고 해당 프로젝트의 콘텐츠(위키 페이지)를 작성하기 위해 먼저 재작성할 문서의 정보 구조를 파악하기 시작했다(2009년 3월쯤). 참고로 이 프로젝트에서 문서를 다양한 포맷으로 배포할 수 있게 하는 것뿐만 아니라 CMS를 공부하면서 배웠던 정보 모델(Information Model)을 구축하려 했고 문서 구성 콘텐츠를 재사용하려고 했다. 그러기 위해 개발자에 의해 작성된 문서를 파악하고 콘텐츠의 유형을 개념 유형(Concept Type), 행위 유형(Task/Procedure Type), 참조 유형(Reference Type)로 구분했다. 또 구분한 단위로 콘텐츠 단위를 조절했다. 문제는 여기서 부터이다. 정보 모델을 구축한 후 문서에 도입하려고 보니 기존의 선형적인 문서(Linear Document) 형태에 맞지 않았다. 정보는 재사용할 단위로 쪼개져 있었고 여기 저기서 특정 콘텐츠를 임베드했다. DocBook 형태로는 더 이상 그 구조를 감당하기 힘들다고 느껴졌다. 태생적으로 DocBook은 콘텐츠 재사용에 잘 맞지 않았다.
그 뒤로 눈에 띈 것은 DITA 포맷이었다. DocBook 포맷이 정보와 스타일의 분리에 대한 패러다임을 보여줬다면 DITA는 CMS의 목적을 이룰 수 있게 정보의 구조, 정보의 타입, 정보, 스타일을 분리시켰다. 특히 같은 형태의 콘텐츠에 대해 정보 구조에 대한 통일성을 줌과 동시에 다양성을 줄 수 있게 DTD를 지원(Generalization, Specialization)했다. 이런 DITA를 이용한 CMS 툴은 현재 여러가지가 있다. 팀에 DITA를 사용한 CMS 툴을 시연하러 온 적이 있다. 그 때 DITA의 실체를 확인할 수 있었으며, 그 다양하고도 막강한 기능에 전율을 느꼈었다. DocBook, DITA와 같은 포맷에 대해 경이로움을 느꼈다(2009년 12월쯤).
그 후로 지금까지 DocBook과 DITA에 대한 경이감은 시들해졌다. 문서를 생산/관리하는 도구의 트렌드가 작성 도구(Authoring Tool)에서 커뮤니케이션 도구(위키, 설치형 블로그)로 넘어가고 있다고 생각하면서부터다. 어떤 포맷을 지켜가면서 문서를 생산해내거나 관리하는 쪽(속도가 더딘 측면)이 아닌, 커뮤니케이션 도구로 작성되는 정보의 폭발적인 생산성(실시간 다수의 협업)과 정보의 최신성을 요구하는 시간적 긴박성, 양방향으로 정보가 오갈 수 있는 상황에서 수시로 들어오는 피드백 적용하는 정보의 유연성 등 커뮤니케이션 도구의 특징에 따르는 문제를 신속하고 최대한 정확하게 처리할 수 있는 방법을 고민하고 있기 때문이다.
2년동안 바뀐 인식 변화를 보면서 앞으로 내가 가지고 있는 생각이 더 빨리 바뀌어야 한다는 것을 느낀다. 그래서 이 분야가 재미있다. 그나저나 글을 가볍고 짧게 작성하려고 했으나 글이 길고 무거워져 버렸다.
시작하는 글
우여곡절 끝에 테크니컬 라이터(Technical Writer)라는 직무를 배정받아 회사에서 일하고 있다. 테크니컬 라이터로 일하면서 배우고, 연구했던 일을 이 블로그에 조금씩 남기려고 한다. 기록을 남기는 일(메모, 일기, 사진 등)을 좋아하지 않는 편인데, 조금씩 필요하다는 생각이 최근 들게 되었다.
전공이 '컴퓨터교육'인 나에게 이 직무가 있다는 것을 입사할 때 처음 알았다. 팀에서는 주로 사내 개발자 대상의 내부 개발 문서(Programming Guide, Api Reference 등), 외부 개발사 대상 문서를 만들었다. 어떻게 보면 API 라이터(API Writer)에 더 가까웠다고 할 수 있다.
개발 부서(초안 작성자)에서 다양한 문서 형식(Microsoft Word, HTML, Wiki, API 문서 자동화 생성을 위해 태깅된 소스 파일 등) 으로 작성된 초안을 받았다. 팀에서는 받은 초안을 주로 Micorsoft Word 문서 형식으로 재작성하였다. 그 후 변환 툴 Doxygen, Javadoc, Jsdoc, Adobe Robo Help, Madcap Flare, Adobe PDF 등을 이용해 Microsoft Compiled HTML Help, WebHelp(.html) 등으로 배포하여 업무를 완료하였다. 물론 그 사이에 문서 작성 프로세스가 있지만 이 포스트에서는 생략한다(추후 관련 내용 작성).
신입이라 2~3년은 문서를 쓰면서 문장력을 늘리거나 팀 내 라이팅 스타일을 지키는 것과 같이 아주 기초적인 부분을 탄탄히 다지는데 나의 모든 리소스를 투자할 것 같았다. 그런데 팀 배정 6개월 정도가 지나서 나는 특별한 프로젝트(?)에 투입된다. 이 프로젝트로 인해 기존에 팀에서 수행하는 업무 방식에 비효율성을 느꼈고 그것을 해결하기 위해 새로운 것을 공부하게 된다. 그 때부터 CMS(Content Management System), Single Sourcing, DocBook, XSL, FOP, MediaWiki 등을 파고 들기 시작했다(앞으로 포스팅할 내용이기도 하다.).
입사해서 근 2년동안 위에서 언급한 내용을 진행하면서 부딪친 문제점, 해결책 등과 연관지어 이 블로그에 남겨볼까 한다.