매뉴얼 구조화

많은 글쓰기 지침들이 차례의 중요성을 강조한다. 차례 짜기가 문서 기획에서 상당 부분을 차지해야 한다고 말한다. 많은 사람들이 아래와 같이 여러 수준을 사용하여 문서를 구조화한다.

장 (Chapter) 1
절 (Section) 1.1
절 (Section) 1.1.1
절 (Section) 1.1.1.1

하나의 문서는 여러 주제들로 이루어진다. 어떤 주제에서 그 내용이, 그 내용의 길이와 관계 없이, 주제를 완결적으로 다루었을 때 그 주제가 독립적인 것으로 간주된다. 현미로 맛있는 밥을 짓는 방법으로 이야기가 시작해서 현미가 백미보다 건강에 좋은 이유로 이야기가 끝난다면 그것은 아직 사람들에게 보여줄 수 있는 글이 아니다. 다층 구조로 이루어진 글에서 우리는 몇 가지 의문을 갖게 된다. 위의 예를 사용하자면, “절 1.1.1.1″에 실제 주제와 내용이 들어있다면 상위 구획들은 무엇을 위한 것들일까? 그것을 아래와 같이 바꾸어 보아도 될 것 같다.

대주제
소주제
소주제
소주제
내용

장 단위를 대주제라기보다 같은 성격의 주제들을 담은, 그래서 다른 주제들과 쉽게 구분할 수 있게 하는 바구니 정도로 보아도 괜찮을 것이다. 그렇다면 “절 1.1″과 “절 1.1.1.”도 바구니일까, 아니면 큰 소주제와 작은 소주제일까? 바구니로 본다면 중간에 아무 내용 없이 큰 절의 제목에 이어 작은 절의 제목이 곧바로 올 수 있을 것이다. 바구니가 아니라면 큰 절 제목 아래 작은 절을 소개하거나 암시하는 문단이 있을 것이다. 이 두 가지 방식이 무분별하게 함께 사용된다면 독자들에게 큐브처럼 보이는 문서가 만들어질지도 모른다.

topics_cubic

문서의 많은 부분을 읽고 난 뒤에 독자들은 그 내용의 총체적 이해로서 어떤 체계적 형상을 머리 속에 그릴 수 있을지도 모른다. 그 형상이 그 문서가 의도하는 것과는 다소 다르다고 하더라도 그렇게 할 수 있을 정도로 독자가 내용을 이해했다면 문서는 제 역할을 한 셈이다. 독자가 어차피 머리 속에 큐브와 같은 것을 갖게 된다면 문서가 아예 큐브를 보여주는 것이 더 좋을지 모른다. 그러나 그런 기대는 달성되지 않는다. 독자는 문서를 통해 여러 주제들을 하나씩 이해하게 되고 그 모듈들을 짜맞추어 큐브를 완성한다. 큐브의 여러 면을, 또는 한 면의 여러 속성을 동시에 보여주는 것은 독자의 이해를 돕기는커녕 문서 자체를 풀기 어려운 퍼즐로 만들어 버린다.

벼락치기 공부를 하면서 만든 쪽지는 그것을 만든 사람에게만 도움이 된다. 공부하는 동안 많은 양의 정보가 이해되고 기억되었고 쪽지는 단지 그 기억을 끄집어내는 데에 도움이 될 뿐이다. TED 강연들을 보라. 보통의 이야기 방식으로 전달되는 정보가 쉽게 이해되고 오래 기억된다.

문서의 구조는 단순해야 한다. 빨랫줄에 걸린 옷들이나 암실에서 줄에 걸린 채 인화를 기다리는 사진들 같아야 한다.

topics_linear2

topics_linear

“절(section)만 사용하되 불가피한 경우에 부절(subsection)을 사용하겠다”거나 그에 준하는 원칙을 세우고 지켜라. 복잡하지 않는 구조는 독자가 이해하기 쉬울 뿐만 아니라 저자가 주제를 정하는 데에도 도움이 된다. 복잡한 구조를 사용하면 이것과 저것을 나누고 무엇부터 무엇까지 담을지 계속 고민하고 갈등하게 된다. 독립적이고 완결적인 것들이 될 때까지 주제들을 나누고 쪼개라. 그렇게 하여 얻은 것들을 논리적인 순서로 연결하라. 아래 전자책 앱의 차례가 단순 구조의 좋은 예를 보여준다.

  1. Purchasing books
    1. Canceling purchases
    2. Free books
  2. Reading books
    1. Navigating through pages
    2. Page appearance
    3. Annotating books
    4. Searching for words
    5. Referencing
    6. Bookmarks
    7. Syncing reading progress
  3. Managing books
    1. Sorting books
    2. Changing display modes
    3. Deleting books
    4. Searching for books
    5. Syncing books

제품의 구성이나 기능이 복잡하다는 것이 문서마저 복잡해야 한다는 이유가 될 수 없다.

문서 개발 프로세스

조앤 해코스(JoAnn Hackos)는 “문서화 프로젝트 관리 (Managing Your Documentation Projects)”에서 문서 개발 프로세스를 다섯 단계로 나눈다.

  1. 정보 계획 (information planning): 문서 기획에 필요한 정보를 수집하고, 문서 얼개를 대략적으로 계획한다. (10%)
  2. 내용 상세화 (content specification): 보다 상세한 정보를 수집하고, 세부 단위까지 문서 구성과 내용을 계획한다. (20%)
  3. 실행 (implementation): 짜여진 계획에 따라 내용을 작성하고, 삽화를 그리고, 문서를 조판한다. (50%)
  4. 발행 (production): 필요하다면 번역하고, 인쇄나 배포가 가능한 형태로 문서를 마무리한다. (19%)
  5. 평가 (evaluation): 계획대로 프로젝트가 진행되었는지 평가한다. (1%)

둘째 단계가 주목할 만한다.  이 단계가 의미하는 바는

  • 무엇을 화제(topic)로 삼을 것이며,
  • 그에 대해 무슨 정보를 제공할 것이며,
  • 그것이 어떤 더 큰 주제 아래 올 것인지

이 단계에서 모두 결정되어야 한다는 것이다. 세째 단계가 가장 많은 시간을 차지하지만 실행 단계에서 고민할 것들은 그다지 많지 않다. 만들어져야 할 내용들이 이미 모두 결정되어 있기 때문에 이 단계에서 고민해야 할 것들은 그 내용들을 어떻게 표현하느냐이다. 무슨 용어를 사용할지, 어떻게 판면을 디자인할지, 어떤 문체를 사용할지 (IBM 스타일을 따를지 아니면 마이크로소프트 스타일을 따를지) 이 단계에서 결정해야 한다.

이 프로세스는 이상적으로 보인다. 이 프로세스를 잘 따른다면 실패 없이 좋은 문서를 갖게 될 것이다. 이와 같은 프로세스를 흔히 폭포 (waterfall) 개발 모델이라고 한다. 그런데 이 프로세스가 과연 실행 가능한가?

DevModel_ISDM

폭포 개발 모델의 특징을 두 가지로 요약할 수 있다.

  • 앞 단계가 완료되지 않으면 다음 단계로 진행할 수 없다.
  • 각 단계에서 해야 할들이 정의되어 있으며, 그 일들도 순차적으로 진행된다.

이와 같은 프로세스로 진행하려면 기획이 완벽하게 이루어져야 한다. 의사 결정을 요구하는 모든 문제가 미리 예측되어야 하며, 그 각각에 대해 이해당사자들의 다수가 동의하는 답이 주어져야 한다. 이와 같은 프로세스로 문서를 개발하는 것은 많은 경우에 불가능에 가깝다.

소프트웨어 개발에서 최근에 많이 선호되고 사용되는 방법이 애자일 (agile) 개발 모델이다. 이 방법론은 업무 영역을 여러 개의 짧은 단계로 나누고 각 단계의 계획, 수행, 평가를 자주 되풀이하며 각 업무를 점진적으로 그러나 동시에 진행시킨다.

DevModel_iterative

이 방법론은 무계획적으로 보이지만 실제로는 폭포 모델보다 더 짧은 기간에 더 좋은 결과를 낳는다. 그 이유는 기획 단계에서 모든 문제를 예측하고 각 문제에서 가장 좋은 결론을 얻기 위해 필요한 모든 정보를 수집하는 것이 사실상 불가능하기 때문이다. 어떤 경우에 이 두 방법론 가운데 어느 하나가 다른 것보다  우위를 차지할 수 있는지 논하는 것은 그다지 현명하지 않다. 대개 프로젝트에서는 애자일 개발 모델을, 프로세스에서는 폭포 모델을 쓴다고 보는 것이 타당하다.

많은 사람들이 프로젝트와 프로세스를 구분하지 못한다. 프로젝트는 프로세스에 의해 수행되지 않는다. 그렇게 하는 것이 가능하다면 그것은 프로젝트가 아니다.

프로젝트 프로세스
해본 적 없는 일 되풀이하는 일
목적은 새로운 것의 창조 목적은 정립된 업무의 반복을 통한 가치 창출
목표와 계획이 책임자에 의해 변경 상당한 계획과 투장에 의해 변경
지도력이 매우 중요 지도력 불필요
프로젝트는 변화를 창조 프로세스는 변화에 저항

 

자동차 회사가 2인승 전기 자동차를 개발하기로 결정했을 때 전기 자동차를 만들어 본 적이 없다면 그 개발은 프로젝트이다. 프로젝트가 시작되면서 질문들이 넘쳐난다. 어느 정도의 성능을 확보해야 상품으로서 가치를 인정받을 수 있는지, 배터리에 대해 보장할 수 있는 품질 보증의 범위가 무엇인지, 별도의 장비 없이 가정에서 전기 자동차를 충전하는 것이 가능한지 등등 매우 많은 문제들이 의사 결정을 기다린다. 확정된 답들이 정책 또는 프로세스가 된다. 따라서 프로세스는 프로젝트의 부산물이다. 대표적인 것이 제조 프로세스이다. 제조 프로세스가 어떤 순서를 따라 어떤 방법으로 전기 자동차를 조립해야 하는지 정의한다.

개발 프로세스라는 것은 같은 범주의 제품을 개발하는 데에서만 유효하다. 원형 제품에서, 이 경우 2인승 전기 자동차에서, 부품이나 디자인 일부를 바꾸어 새로운 제품을 만드는 것은  설계 변경과  성능 검사의 반복만을 요구할 것이다. 이 과정에서 풀어야 할 숙제는 그다지 많지 않다. 그리고 파생 제품의 제조 프로세스는 원형 제품의 것과 크게 다르지 않을 것이다. 경주용 전기 자동차나 화물용 전기 자동차를 만들기로 했을 때, 2인승 전기 자동차의 개발 경험이 별로 도움이 되지 않는다면 그것은 다시 완전히 새로운 프로젝트이다.

문서를 개발하는 것도 이와 비슷하다. 스마트폰이 처음 개발될 때 매뉴얼 개발자들은 기존의 매뉴얼을 활용하려 했겠지만 오래지 않아 그것이 거의 도움이 되지 않는다는 것을 깨달았을 것이다. 그들은 용어, 표현, 구성, 문체, 삽화 등 거의 모든 점에서, 그 완전히 새로운 제품을 적절하게 설명할 새로운 방법들을 찾아내야 했다. 그 방법들이 적절하다면 (본질적인 변화라 할 수 없는) 새로이 추가된 스마트폰 기능들을 위해 다른 새로운 표현 방법을 모색할 필요가 없다. 새 기능은 추가해야 할 내용일 뿐이다.

문서화 프로젝트에서 애자일 개발 모델을 사용하는 것은 불가피하다. 문서화 프로젝트가 문서화 프로세스가 아님을 이해한다면 어떤 출판 도구가 유리한지 판단하기가 쉬워진다. 테크니컬 라이터가 인디자인으로 원고를 작성한다는 것은 어불성설이다. 그래서 테크니컬 라이터가 워드 프로세서를 이용하여 원고를 작성하고 그것을 인디자인 포맷으로 옮기는 방법이 흔히 사용된다. 하지만 이 비효율적인 방법은 시간을 낭비할 뿐만 아니라 내용의 질적 개선도 방해한다.  프로젝트가 완료된 이후에 그리고 파생 제품의 매뉴얼을 만드는 데에 문서화 프로세스가 제대로 기능할 수 있을 때 인디자인을 쓰는 것이 합리적이다. 만약 매뉴얼의 개정과 번역이 빈번하게 일어날 수밖에 없다면 인디자인을 보완하거나 대체할 수 있는 방법을 찾아야 할 것이다.

모든 문제를 도구로 풀려는 시도는 현명하지 않다. 불필요하거나 부적절한 내용을 제거하거나 간략하게 만듦으로써 필요 이상으로 빈번하게 문서를 개정하는 일을 피할 수 있다.

Material Design and the Technical Communicator

layering (2)Material Design, Google’s design language for Android applications, has permeated both native apps like Gmail and YouTube as well as third party Android apps. Since its introduction in June of 2014, technical communicators and UX designers have explored new ways to incorporate the principles of Material Design in their workflows and products.

Material Design relies on three key principles:

  1. Material as a metaphor

The interface provides visual cues grounded in surfaces and edges that resemble those found in reality. These cues convey how objects move and exist in the visual space and react in relation to each other. For example, cards have edges and shadows, much like cards in the real world, to indicate that they are distinct from each other.

  1. Bold, graphic, and intentional elements

The elements on the screen, such as the text, space, colors, and images, convey the hierarchy, meaning, and focus of each element and provide guidance to the user. For example, the opacity of the text in the app can convey how important its information is compared to the other text on the screen and focus the user’s attention.

  1. Motion to provide meaning

All action takes place in a single environment that uses motion to transform the design and layout of the screen for different functions. For example, a settings panel can slide out from the side of the screen to provide access to settings without the app switching to a new screen.

The good news is that these principles seek to make apps more intuitive and uniform, so technical communicators won’t have to spend a lot of time teaching users how to navigate apps. The bad news is that technical communicators need to spend a lot more time testing the nonverbal cues, such as the icons, textures, and images, and verbal cues, in their app.

In most cases, tooltips and taglines are enough to teach users how to use a simple app. However, the rise of touchscreen devices has eliminated traditional tooltips, and taglines aren’t always appropriate or aesthetically pleasing. In these cases, elements like screen overlays and cards can provide instructional content in a style that matches the Material Design aesthetic. For example, you may want to provide a short series of cards as a slideshow that describes what’s new when you release a substantial update. Or, you may want to provide a tooltip overlay to describe the most important elements on the screen when users start your app for the first time.

Material Design values flexibility, so users should be free to input information without encountering too many errors. However, when an error does occur, the app should handle the error in the following way:

  1. Communicate what occurred.
  2. Provide steps to resolve the error.
  3. Preserve information already input by the user.

With the exception of the third step, this form of error handling doesn’t differ too much from the error messages patterns_errors_userinput2guidelines proposed by Microsoft. In fact, most of the
recommendations for good technical writing, such as brevity and clarity, still apply in Material Design. The only difference is the delivery method. Instead of writing a static user guide, technical writers can now incorporate their information directly into the app. For example, in the figure to the right, the red text communicates why the information entered is incorrect and how to fix it without requiring the user to refer to a separate document or leave the screen.

Mobile devices are pushing technical writers into new and exciting roles. Understanding the principles of Material Design and the iOS Human Interface Guidelines will allow technical communicators to comfortably shift from providing background documentation to providing information at a glance.

둘 이상의 언어로 만들어야 한다면 원문을 영어로

기술 문서의 번역에서 대부분의 사람들이 세 가지 언어만이 한국어에서 직접 번역하는 것이 가능하다고 여기고 있다. 영어, 일본어, 그리고 중국어가 이에 해당된다. 엄밀히 말하자면 한국 안에서 어렵지 않게 구할 수 있는 번역사들이 사용하는 언어가 이 세 가지에 국한되어 있다. 한국어에서 러시아어로 번역할 수 있는 사람을 찾는 것이 불가능하다고 말할 수 없겠으나 그것은 여전히 요행을 바라는 것에 지나지 않는다. 번역 회사들은 사업을 요행에 맡기지 않는다. 그들은 제휴할 수 있는  번역 회사나 번역사들을 러시아에서 찾는다.  물론 한국어에서 바로 러시아어로 번역할 수 있는 사람은 러시아에도 없다고 봐야 한다. 영어는 실제 만국 공통어이고, 번역 업계에서 대부분 영어가 원문의 언어라고 간주한다.

번역비는 번역사가 속한 국가의 임금 수준을 따른다. 일본어로 번역해야 하는 프로젝트에서, 낮은 비용이 가장 중요한 요소라면 한국어로 원문을 작성해야 한다.  그 프로젝트를 맡게 된 번역 회사는 당연히 일본보다 번역료가 싼 한국에서 번역사를 구할 것이다. 그러나 질이 중요하다면 영어로 원문을 작성해야 한다. 두 나라 모두에서 한국어와 일본어를 하는 번역사의 수보다 일본에서 영어를 하는 번역사의 수가 훨씬 더 많기 때문이다. 더 많은 번역사가 더 좋은 번역을 결정적으로 담보할 수 없을지라도 그 개연성은 매우 높아진다. 적절한 번역사를 구하기 어렵더라도 수주를 포기하는 번역 회사는 없다. 그들은 고객이 까다롭지 않기를 바라면서 자격 없는—이제 대학을 갓 졸업한 햇병아리 번역사에게—일을 맡길지도 모른다.

검증된 번역사일지라도 항상 좋은 결과를 내놓기 어렵다. 내용의 어려움—특히 접해본 적이 없는 분야라면, 일정, 건강 상태 등 번역 품질에 영향을 미칠 만한 요인들은 많다. 번역 품질을 일정하게 유지하기 위해 많은 번역 회사들이 번역 검사를 전담하는 사람들을 두고 있다. 대부분 영어를 모국어로 사용하는 나라에서 온 외국인이나 교포들이다. 일본어 전담자를 둔 번역 회사들은 드물다. 그런 전담자를 채용해야 할 만큼 물량이 많지 않을 뿐만 아니라 그런 일을 할 만한 사람을 구하기 어렵기 때문이다. 이 사정이 원문을 영어로 해야 하는 또 다른 이유이다. 한국어에서 일본어로 번역된 문서가 다른 이에 의해 적절하게 번역되었는지 검토되었기를 기대하기 어려우나, 일본어에서 영어로 번역되는 경우라면 그것을 요구하는 것이 의뢰자에게 어려운 일이 아니다.

동일한 테크니컬 라이터가 작성하고 동일한 번역사가 작업할지라도—두 사람 모두 훌륭하다면, 영어본에서 번역한 경우에 영어본과 한국어본 모두가 그 반대의 경우보다 더 좋기 마련이다. 여러 이유들 가운데 하나는 기술 문서를 주로 다루는 번역사들에게 동일한 분야의 문서를 다루는 기회가 많이 주어지지 않고 그래서 그 분야에 대한 지식이 깊이 축적되지 않는다는 데에 있다. 내용에 따라 번역사들을 크게 세 부류로 나눈다.

  • 영상물 번역
  • 출판물 (단행본) 번역
  • 기술 문서 번역

영상물은, 의학 드라마 같은 예외적인 경우를 제외하면, 그 내용에 대해 그다지 높은 수준의 지식을 요구하지 않는다. 영상물 번역사는 전문 지식을 배우는 것보다 자연스럽게 읽히거나 들리도록 옮기는 일에 더 많은 노력을 기울일 것이다. “I know what I’m doing”을 “난 바보가 아냐” 따위로 옮기는 것이 한 예이다. 출판물 번역사에게는 매우 높은 수준의 전문 지식이 기대된다. 다행히 이 기대가 대체로 충족되는 것 같다. 출판물 번역사들은 자신이 잘할 수 있는 그리고 좋아하는 것만을 골라 하는 것처럼 보인다. 그들은 대개 한 가지 분야의 서적들만을 다룬다. 경제학 책들을 번역하면서 생물학 책들도 번역하는 번역사들은 없다. 이에 반해 기술 문서 번역사들은 일에서 자기의 취향과 선호를 고집할 수 없다. 어제는 태블릿 앱의 문서를, 오늘은 담수화 장치의 것을 번역해야 한다. 소프트웨어 공학에서 쓰이는 중요한 개념들을 올바르게 이해하기에 번역사들에 주어진 시간이 턱없이 부족하다. 출판물 번역사들이 하는 것처럼 특정 분야의 일만을 골라 하는 것은 기술 번역사들뿐만 아니라 테크니컬 라이터들에게도 가능하지 않다. 그러나 테크니컬 라이터들은 전문 분야의 지식을 축적할 수 있는 기회와 시간을 번역사들보다 훨씬 더 많이 갖는다. 의뢰자들이 자신들의 제품에 쓰인 기술들을 테크니컬 라이터들에게 이해시키는 데에 적지 않은 시간이 듦을 깨달으면 그들은 둘째 일을 같은 테크니컬 라이터가 맡기를 원한다. 아무도 자신들의 엔지니어들이 새로운 테크니컬 라이터를 위해 시간과 에너지를 소모하면서 같은 일을 되풀이하기를 원하지 않기 때문이다.

원문을 한국어가 아닌 영어로 작성해야 하는 또 다른 이유는 한국어와 영어 사이에 존재하는 언어적 특성의 차이가 매우 크다는 데에 있다. 영어는 한국어보다 훨씬 더 많은 어휘와 표현 장치들을 갖고 있다. 영어가 한국어보다 훨씬 더 정확하게, 정밀하게, 그리고 상세하게 묘사할 수 있다. 한국어와 영어 사이에 등가 번역을 기대하기 어렵다. 한국어 문장을 영어로 옮기고, 그 영어 문장을 다시 한국어로 바꿀 때, 원래 한국어 문장과 동일하게—아니면 적어도 유사하게 번역되기를 기대하기 어렵다는 말이다. 극단적으로 말하자면, 영어에서 한국어로의 번역은 대개 내용의 복잡도를 떨어뜨린다. 원문이 충분히 상세한 정보를 담고 있다면 번역에서 발생하는 의미의 손실은 미미해서 번역문을 이해하는 데에 큰 어려움이 없다. 그런데 한국어에서 영어로 번역하자면 한국어에 없는 요소들, 특히 관사를 추가해야 한다. 영어 문장에서 엄밀함을 위해 요구되는 모든 요소들을 한국어 문장에서 나타내면 대분분의 사람들이—문맥에 의지하여 해석하려는, 영어에 비해 상대적으로 강한 성향 때문에—그것을 불필요하게 장황하다고 느낀다. 이러한 습성 때문에 테크니컬 라이터는 할 수 있는 것보다 덜 치밀하게 문서를 작성한다. 그래서 영어로 작성했더라면 달성되었을 정밀함이 고스란히 번역사의 몫이 되지만,  내용에서 의지할 만한 힌트를 찾아내기에 충분한 시간이 번역사에게 주어지지 않는다.

 

내용이 유사하다는 전제 아래, 한국어에서 영어로 옮길 때 오역의 가능성이 그 반대보다 높아진다. 일본어나 중국어 이외에 다른 언어로 된 번역본이 필요할 때, 이 문제는 훨씬 더 심각해진다. 원문이 영어로 작성되었다면 한국어를 비롯하여 다른 모든 언어들로 동시에 번역할 수 있다.  그러나 한국어로 원문이 작성되었다면 영어로 번역하고 그것을 다시 스페인어나 핀란드어로 옮겨야 한다. 이중 번역으로 인해 오역의 가능성은 높아지고 번역 기간도 두 배로 늘어난다.

번역사가 한국어 문서를 영어로 옮기는 것보다 테크니컬 라이터가 처음부터 영어로 작성하게 하는 것이 훨씬 더 좋은 결과를—오역이 훨씬 더 적은 번역본들과 짧은 번역 기간을 가져올 수 있다. 이렇게 하는 데에 현실적으로 장애가 전혀 없지 않다. 영어에 능한 테크니컬 라이터가 아직 많지 않으며, 많은 의뢰자들이 영어로 작성된 문서를 검토하는 것에 거북함을 느낀다. 그러나 당장의 이 장애와 불편을 감수하지 못하면 이 문제를 궁극적으로 극복하지 못할 것이다.

테크니컬 라이터의 고유 능력

테크니컬 라이터(technical writer)는 기술적인 정보를 전달하는 문서를 작성한다. 말 그대로 技術 作家이다. 이들이 다른 저술가들과 어떤 점에서 다른지 살펴 보겠다.

저술과 관련된 일을 하는 사람들이 많다. 조선학 교수는 석유 시추선에 대해, 의학 전문 기자는 메르스에 대해, 서울시의 홍보 담당자는 서울역 고가도로의 공원화에 대해 글을 쓴다. 이런 사람들에 비해 테크니컬 라이터만이 갖고 있는 고유한 능력이 있을까?

글쓰는 사람들은 모름지기, 교열가의 도움을 받는다 해도, 문법과 어법에 대해 상당한 지식을 갖추어야 한다. 그러니 테크니컬 라이터도 당연히 자기가 사용하는 언어를 공부해야 한다. 그러나 다른 이들에 비해 테크니컬 라이터에게 더 높은 수준의 어학 지식이 요구되는 것은 아니다. 그러므로 이 점에서 테크니컬 라이터의 고유한 능력을 찾을 수 없다.

다른 사람들에 비해 테크니컬 라이터는 출판 소프트웨어를 잘 다루어야 한다. 그 능력이 필수적이라고 할 수 없으나 출판 소프트웨어를 잘 다룰수록, 타이포그래피에 대한 식견을 많이 갖출수록 높은 경쟁력을 갖게 된다. 그러나 그것은 “좋은 내용을 작성해야 한다” 본연의 임무와는 거리를 두고 있다. 따라서 이 역시 테크니컬 라이터의 고유 능력이라고 볼 수 없다.

테크니컬 라이터는 글쓰기 방법(writing style)을 알고 있다. “묘사 문장이 20 개 이내의 단어로 이루어지는 것이 이상적이다”라는 것 따위가 그 중 하나이다. 독자의 습성과 편의를 더 많이 고려함으로써 그러한 원칙들이 만들어졌다. 그렇다면 테크니컬 라이팅이 일반적인 글쓰기 방법론과 크게 다르고, 그로부터 테크니컬 라이터의 고유성을 찾을 수 있을까? 이 점이 흔히 크게 강조되지만, 테크니컬 라이팅이 독립적인 영역을 차지할 만큼 특이성을 가졌다고 보기 어렵다. 테크니컬 라이팅 지침과 보통의 글쓰기 교훈 사이에서 차이점들보다는 공통점들이 더 많다.

내용으로 눈을 돌려 보자. 테크니컬 라이터가 작성한 글은 정보를 담고 있다. 학자나 기자가 작성한 것들도 정보를 담고 있다. 그런데 여기에서 약간의 차이가 발견된다. 스마트폰을 소개하는 신문 기사에 비해 그 스마트폰의 사용 설명서는 훨씬 더 많은 것들을 아주 상세하게 다룬다. 매뉴얼이 담고 있는 정보의 양이 훨씬 더 많다고 할 수 있다. 그런데 학술서나 논문과 비교하면 덜 전문적이다.

테크니컬 라이터에게 주어지는 특이한 상황은 “잘 알지 못하는 것에 대해 독자에게 필요한 만큼 상세하게 설명해야 한다“는 것이다. 테크니컬 라이터가 전직 엔지니어라고 해도 이 상황은 별로 달라지지 않는다.  한 명의 개발자가 다 설명할 수 있을 만큼 단순한 제품은 그다지 많지 않다. 그리고  깊이 알고 있기 때문에, 필요 이상으로 장황하게 또는 어렵게 설명한다면 그 지식이 도리어 독이 될 수 있다.

테크니컬 라이터를 번역사에 비유할 수 있다. 번역사가 한국어 글을 외국인이 이해할 수 있게 영어로 옮기듯이, 테크니컬 라이터는 엔지니어의 말을 독자가 이해할 수 있는 말로 옮긴다. 번역사가 내용을 제대로 이해하지 못하면 오역하듯이, 테크니컬 라이터가 자신이 작성하고 있는 제품이나 그와 관련된 기술을 올바르게 이해하지 못하면, 독자에게 필요한 정보를 제공하지 못하거나 독자를 이해시키지 못한다.

여기에서 테크니컬 라이터의 고유 능력을 찾을 수 있다.

테크니컬 라이터는 빨리 배워야 한다.  엔지니어가 제공하는 자료나 구두 설명에서 헛점이나 모순을 빨리 짚어내어 되물어야 한다. 모든 것을 엔지니어에게 의존할 수 없기 때문에 인터넷에서 관련 지식을 배워야 한다. 구글이 보여주는 검색 결과들을 빨리 읽고 이해해야 한다.

테크니컬 라이터는 정보의 필터가 되어야 한다.  엔지니어들이 중요하게 여기는 것들 가운데 어떤 것들은 독자에게 필요하지 않거나 혼란을 줄 수 있다. 테크니컬 라이터는 주어진 정보들을 선별하여 어떤 것들을 독자에게 제공할지 적절하게 결정해야 한다.

 

What’s the big deal with XML?

XML (eXtensible Markup Language) is one of those initialisms that remains in the background of the tech industry. It pops up in almost every major office software suite (did you ever wonder what the x stands for in .docx?). It shows up all the websites that use XHTML (about 34% of the websites out there) and each RSS feed that you read. And, if you know any technical writers, they probably won’t shut up about DITA (Darwin Information Typing Architecture).

So, what makes XML so special? Well, the answer depends on who you are and how you use XML. Writers like XML because it gives them full control of their text. Developers like XML because they can easily repurpose content. And, designers like it because they can apply stylistic changes on the fly. But, before we explain these benefits in too much detail, we should probably explain what XML is.

What is XML?

XML stands for eXtensible Markup Language. Like HTML, XML is a markup language. Markup is the information that tells a computer how to read content, such as text. For example, this website uses HTML markup (actually, a combination of HTML, CSS, PHP, and Markdown) to tell your web browser where to display text, what font to use, and when to display a word in bold. Without some sort of markup, it would be almost impossible for your computer to properly display content in web browsers, desktop publishing programs, or even applications like games.

Unlike HTML, XML focuses on what the data is rather than how the data looks. That is, the markup in XML tells the computer the content type, and a separate style sheet tells the computer how to display the content. In HTML, the markup only tells the computer how to display the content. So, if you want to change the font in all of the headings on your HTML webpage, you have to change each one individually. In XML, you can simply change the entry that specifies the heading font in the style sheet.

Another notable difference is that XML doesn’t use predefined tags (tags are units of markup). HTML markup is the same everywhere. So, if you use an <h1> tag in HTML, an HTML reader automatically knows that it is a top-level heading. In XML, a style sheet is needed to define the tag, but you can also name the tag anything you want. For example, you could name it <section_heading>, <page_heading>, or even <the_only_heading_you_will_ever_need>. This is what puts the eXtensible in eXtensible Markup Language (XML), and you can create as many tags as you want – which means that you can make your content as nuanced or lightweight as you need.

So, why is XML so great?

Extensibility

XML emerged as a response to the inflexibility and inefficiency of HTML. The standard on which XML is based, SGML (Standard Generalized Markup Language), was deemed too complex, so XML was made to simplify it. XML ditches the unnecessary elements of SGML while still retaining the key principles that the markup needs to describe the content. By abandoning predetermined tags and unnecessary elements and allowing content creators the flexibility to create their own tags, XML offers a lightweight and flexible solution for transporting information, especially text.

Extensibility also makes XML easier to use and maintain than other markup languages. Authors can intuitively name tags based on their functions. Consider the following example.

< ?xml version="1.0" encoding="UTF-8"?> 


  
    Dear Mr. Hughes,
  
  
    I so enjoyed your last film and do hope that you make another.
  

Based on the names used in the tags, you can infer the basic structure of the document and the type of content that each tag contains. Furthermore, you or a new employee could return to this document several years down the road and still figure out what the tags mean.

Strictness

XML is also far stricter than HTML. The rigid syntax required by XML results in smaller, faster, and lighter browsers. For example, XML is stricter than HTML in the following cases:

  • Case sensitivity: HTML is not case sensitive, while XML is.
    A <Paragraph> tag is not the same as a <paragraph> tag.

  • End tags: HTML lets you get away with not closing elements, while XML doesn’t.
    A <p> tag won’t work without the corresponding end tag (</p>).

  • Quotation marks: HTML lets you use value delimiters without quotation marks, while XML doesn’t.
    <object width=100> won’t work, but <object width=”100”> will.

  • Nesting: HTML lets you overlap elements, while XML doesn’t.
    <b><i>Cattle</b></i> won’t work, but <b><i>Cattle</i></b>.

In the past, some Internet browsers devoted up to 50% of their code to correct the mistakes or inconsistencies in HTML content. By imposing a more rigid set of rules, browsers and other programs that process text (often called parsers) no longer need to account for mistakes in the markup. Paying a little more attention when writing is a small price to pay for better overall performance.

In addition to being strict about syntax, XML can also include rules about the structure of your documents. For example, if you were creating an employee database, you could create an <employee> element that must contain <first_name> and <last_name> elements. Doing so ensures that the required information is included and that all unnecessary information, such as an employee number, is excluded.

Easy Data Exchange

Although extensibility and simplicity added to its early success, XML’s greatest claim to fame is that it allows authors to easily publish the same content to different media. Because XML concentrates only on the content type, the content remains independent of the medium. So, authors can write and edit a document in XML and publish it to a website, user’s manual, and helpdesk script. This facet of the XML is often touted as single-source – multi-target. In fact, content reuse has catapulted DITA, an XML standard maintained by OASIS Technical Committee, to the forefront of the technical writing world.

Furthermore, XML relies on free open standards, such as the XML 1.0 Specification, so it avoids the bulk, complexity, and inaccessibility of propriety data formats, such as those used in the older versions of desktop publishing applications like Word. XML content and markup is stored as text that authors can configure directly. Even when using an XML editor, such as FrameMaker, authors can still output the XML text to make changes or transfer the content to another format.

Conclusion

So, back to the question at hand: What makes XML so special? Well, it’s right there in the name: extensibility. Writers and developers are constantly finding new ways to use XML to accomplish their goals in a variety of media formats, and XML supports the freedom they need to do it. That, coupled with its ability to be intuitive and strict in both code and structure and easily distributed to multiple channels means that XML will continue to be a staple of the IT community for years to come.

WYSIWYG과 WYSIWYM

WYSIWYG (What You See Is What You Get) 인터페이스를 사용하지 않는 소프트웨어를 찾기 어려울 만큼 이제 위지익은 아주 당연한 것으로 간주된다. 마이크로소프트 워드를 비롯한 인쇄 기능을 제공하는 모든 소프트웨어가 그야말로 화면에서 보이는 대로 내용을 인쇄한다.

위지윅은 편리의 상징이고, 인터페이스가 편리할수록 효율성이 높아진다. 그러니 위지윅이 좋아질수록 효율성이 높아진다고 기대할 수 있겠다. 그런데 위지윅 인터페이스가 한계 없이 향상될 수 있을까? 인디자인은 메뉴바와 툴바에 다 담을 수 없을 만큼 많은 기능들을 제공한다. 이 문제에 대한 해법으로서 인디자인은 패널들을 사용한다. 사용자들은 필요한 패널들만 화면에 표시되게 할 수 있다. 기능이 들어날수록 사용성의 복잡도가 증가한다. 하나의 업무 목적을 달성하는 데에 다양한 방법들이 가능한데 위지윅은 특정 방법을 종용하지 않는다. 사용자들은 똑같은 거리를 두고 그 방법들에 둘러싸여 있다. 어느 방법을 선택하든, 그 결과가 어떠하든 그것은 사용자들의 몫이다.

위지윅의 대척점에 있는 것이 WYSIWYM (What You See Is What You Mean)이다.  어떤 출판 소프트웨어든 마크업을 사용한다. 마크업 언어는 아래와 같이 크게 세 가지로 나뉜다.

  • Presentational: 마이크로소프트 워드, 어도비 인디자인
  • Procedural: 레이텍, 포스트스크립트
  • Descriptive: HTML, XML

Presentational 마크업이 위지윅을 , 나머지 두 마크업이 위지윔을 지향한다. 여기에서 주목할 것은 위지윅 파일들은 바이너리 포맷인데 반해, 위지윔 파일들은 텍스트 포맷이다. 이 둘 사이에서 가장 큰 차이는,  텍스트 포맷에는 외부 프로그램이 접근하고 조작할 수 있지만 바이너리 포맷에는 그럴 수 없다는 것이다. 이를 이해하기 위해 마크다운을 살펴보자.

마크다운(markdown)은 경량(lightweight) 마크업 언어들 가운데 하나이다.  또 다른 경량 마크업 언어로 AsciiDoc과 reStructuredText가 있다. 이것들의 문법(syntax)은 위키의 것과 비슷한 정도로 매우 단순하다. 이 그림이 마크다운 문서에서 만들어진 HTML과 PDF를 보여준다.

markdown_pdf_html

마크다운의 미덕은 “내용 작성에만 집중할 수 있기 때문에 더 짧은 시간에 더 좋은 글을 작성할 수 있다”는 것이다. 마크다운 사용자들은 인디자인에서 구현할 수 있는 것과 같은 정교한 레이아웃 디자인을 기대하지 않는다. 그것이 덜 중요하다고 믿기 때문이다. 그들은 오로지 내용에만 집중한다.

위지윅의 또 다른 대척점으로서 떠올릴 수 있는 것이 명령 프롬프트(터미널 또는 콘솔이라고도 한다)이다. 위지윅이 보편적인 인터페이스로 정착되면서 명령 프롬프트가 좀처럼 사용되지 않는다.

cmd

명령 프롬프트를 사용한다는 것은 파워셸이나 파이썬 같은 스크립트 언어를 사용한다는 것으로 볼 수 있다. 스크립트 언어를 사용하여 위지윔 마크업 언어로 작성된 문서를  조작함으로써 무엇을 얻을 수 있느냐에 대한 답은 당신의 아이디어와 그것을 구현하는 프로그래밍 능력에 달려 있다. 이상적으로 말하자면 당신이 원하는 거의 모든 것이 가능하다. 흥미로운 사실은 윈도우즈에서 명령 프롬프트 사용이 점차 줄어드는 반면, 터미널을 아예 제공하지 않았던 맥에 OSX와 함께 터미널이 도입되었고, 그 뒤로 터미널 사용이 증가하는 추세에 있다는 것이다.

텍(tex 또는 latex이라고 한다)은 프로그래밍이 가능한 마크업 언어이다.  단어들의 첫 글자만 다르게 표현하도록 만드는 것이 텍에서는 어렵지 않다.

emphasizing_initials

다양한 언어의 처리, 정교한 조판, 내용의 선택적 재사용, 최소한의 수동 작업, 용이한 협업 등 많은 것들이 다큐멘테이션 솔루션에 요구된다. 그 중 어느 하나라도 충족하지 못하면 선택되기 어렵다. 이 모든 조건들을 만족하는 솔루션을 위지윅 방법으로 만들 수 있을 것이다. 하지만 그 대가로 우리는 엄청난 비용을 지불해야 한다. 위지윅이 생산성 향상에 장애로 작용하고 있고, 이제 그 한계에 이르렀다고 볼 수 있다. 위지윔이 확산되고 있음을 보여주는 징후들이 늘고 있다. 마크다운을 비롯한 경량 마크업 사용의 증가가 그 중 하나이다. 텍 관련 소프트웨어와 웹 서비스가 최근 몇 년 동안 급속도로 늘어났음이 또 다른 징후이다. 위지윅이 주는 편의는 강력하지만 문서화 작업에서 점차 증가하는 시간과 비용의 압박을 이겨낼 만큼은 아니다. 위지윔이 위지윅을 배척하거나 대체하기 위해 등장한다기보다 위지윅의 한계를 극복하려 한다고 보는 것이 타당할 것이다. 위지윔이 보편적인 것으로 인식될 무렵에 프로그래밍 능력이 우리에게 새로운 도전이 될 것이다.

Tame Wild Writers with a Style Guide

A writer’s room without a style guide is like the wild west: cowboys making their own rules, lawlessness and grammatical errors, and gunfights at the OK corral. Alright, the last one might be a bit of a stretch, but the other points still stand. This article discusses how to bring law and order to your writer’s room through a codified manual of style. This process might not be easy, and you may have a few showdowns at high noon, but in the end you’ll end up with a functional community of writers all working towards the same goal.

Finding Support

The most essential, and perhaps hardest, part of writing a style guide is receiving support from your company. Of course, your company would love a style guide to flash to clients and keep their writers in line, but they’re not likely to schedule time that could be spent doing billable work making a style guide. So, the first step in creating a style guide is convincing your managers of its worth. Thankfully, style guides offer a number of benefits that appeal to budget-conscious managers.

First, style guides save your team time in the long run. Style guides allow writers to concentrate on the content without being distracted by having to look up documentation and grammar conventions. Furthermore, they don’t need to be extensively briefed on matters of style when taking over a project from another writer. Finally, style guides cut down on debates between writers (at least the ones concerning grammar and punctuation), which saves everyone a lot of time and a little bit of tension in the office.

Second, style guides develop a brand that your company can leverage. Many companies, including Latis Global Communications, employ multiple writers at any given time. Often, there’s no guarantee that we can assign all of the projects from as client to a single writer, so the style used for a user’s guide may not match the one used for the accompanying administration manual. In fact, even the titling conventions may differ! A comprehensive style guide, well implemented, ensures that the style and voice of the writing remains consistent throughout all of a company’s projects.

Getting Started

After you’ve convinced your boss that a style guide is a valuable tool, you face another sizable challenge: the writer’s room. Writers – whether technical or not – hold fast to their views, especially with matters of grammar and punctuation. My first time implementing a style guide, I decided no harm could come from a simple open forum among the writers to start things off. Of course, the forum quickly dissolved into a generational battle about issues such as contractions in manuals and ending sentences with prepositions, so this was not the smartest option.

Instead, you should appoint someone to act as a style sheriff. The style sheriff is responsible for writing and maintaining the style guide as well as settling disputes regarding style issues. The style sheriff should have an eye for details and a genuine interest in matters of style. Look for the writer with the most well-worn copy of Struck and White. It also helps if the sheriff is appointed by someone in charge, such as a division head or team manager, in order to avoid some of the disputes that are bound to arise with one writer dictating matters of style to the others.

As their first action, the style sheriff should choose a base style guide to inform their decisions. The most popular style guides for the IT market are the IBM Style Guide: Conventions for Writers and Editors and the Microsoft Manual of Style for Technical Publications. The former advocates a tone similar to that used in academic writing, while the latter promotes a more conversational tone. Either style guide is acceptable. However, these style guides should only inform stylistic decisions. The lengths of these style guides (389 pages and 464 pages, respectively) make them difficult to memorize for new writers. 20-30 pages is a better length for an internal style guide because new writers can easily digest it in a night and master it in a week.

Depending on your industry, you may want to consider authoring a glossary in conjunction with the style guide. The Microsoft Manual of Style for Technical Publications contains a substantial glossary of user-facing technical terms. However, you may want to use a more technical glossary, such as the IEEE Standard Glossary of Software Engineering Terminology, or even a controlled language glossary, such as glossary found in the Aerospace and Defense Simplified Technical English standard. Whichever you choose, you should treat the glossary in much the same manner as the base style guide. That is, you should incorporate entries from the base glossary into an internal glossary that contains only those entries relevant to your company in order to enhance the usability of the glossary. Tips on how to create a glossary will be covered in a future blog entry.

Lists and Meetings

After selecting a base style guide, you can start considering what to include in your internal style guide. Include too many topics, and users won’t be able to effectively memorize the style guide. Include too few topics, and users won’t be able to find the answers they need.

A good strategy when first developing your style guide is to list all of the topics covered in the base style guide. Then, armed with this list, review three or four recent projects and check off any style topics that match aspects of the project. For example, if the projects contain tables, then, naturally, you should check off the topics related to tables in your list. Finally, create a new list that includes only the checked off topics.

Distribute this list among the writers at your company, and then organize a meeting at which the writers can propose new topics. You should also allow the writers to vote on grammar and style issues that may be particularly contentious, such as ending sentences with prepositions and the use of Oxford commas. At the conclusion of the meeting (or series of meetings) you should know the topics that your style guide will contain as well as your company’s stance on most style issues.

Writing the Style Guide

After determining what your style guide will cover, you can finally start the fun part: Making decisions about grammar and punctuation. If that doesn’t sound like fun, then you may want to step down as style sheriff or risk a showdown when you can’t justify not using the Oxford comma.

Each entry in an internal style guide should state a specific rule, outline some of the exceptions to that rule, and then provide an example highlighting the rule. As in the following:

Compound Nouns

Avoid using more than three nouns when creating compound nouns. Use prepositions to clarify noun clusters.

Examples

(O) Maintenance procedure for the operator area

(X) Operator area maintenance procedure

The style guide should abide by the same formatting and style that it recommends. This allows writers to infer answers to style questions while reading, which saves time when looking up multiple issues. Furthermore, your style guide should be just as readable as any other document that you produce. So, it needs an appropriate amount of white space, pages that readers can scan easily, and an intuitive structure. Finally, formatting your style guide in this way ensures that all of your company’s internal documents, such as standard operating procedures and employee handbooks, have a consistent style and appearance.

In addition, you should author your style guide using the software most often used by your company. For example, if your company uses Microsoft Word, then you shouldn’t author your style guide in Pages. Furthermore, you shouldn’t author your style guide using a tool or markup language that is unfamiliar to members of your team. For example, if your team regularly authors documents in XML, then it wouldn’t make sense to author your style guide in Markup.

Distributing the Style Guide

After writing the style guide, determine whether your writing team would benefit most from a physical copy of the style guide, an electronic copy of the style guide, or both. If publishing the style guide electronically, select a format that uses a program openly available to your writers, such as PDF. If publishing hard copies of the style guide, consider distributing the guides in small binders so that the information can be easily updated without incurring too many additional costs.

You should then distribute the style guide in conjunction with a kickoff meeting involving all of the writers and other personnel that will use the style guide. This meeting should instruct the personnel how to effectively apply the style guide to their writing and the scope to which it applies. For example, you should specify whether the style guide applies to all documents and written correspondences or only those that the customer will see. You should also specify who will update the style guide and how personnel will be notified of such updates.

Conclusion

A good style guide can help you bring law and order to an unruly community of writers. However, implementing a style guide requires tenacity, strength, and the support of your company. It also helps if you’re organized and have a plan of action. I’ve armed you with the plan, so it’s time for you to strap on that sheriff’s badge and set the town straight.

출판 소프트웨어를 선택할 때 고려해야 할 것들

매뉴얼 개발에서 가장 먼저 맞닥뜨리는 문제가 출판 도구의 선택이다. 다음 세 가지 파일 형식이 매뉴얼 매체로서 사용된다.

  • PDF
  • HTML
  • 동영상

매뉴얼 매체로서 HTML과 동영상이 점점 더 많이 주목받고 있으나, 아직은 소프트웨어 산업에 국한되어 있다. 이 글에서는 PDF 제작의 관점에서만 출판 도구들을 다루겠다.

출판 도구를 선택할 때 다음과 같은 점들이 고려된다.

  • 타이포그래피
  • 효율성
  • 비용

위의 기준들을 갖고 마이크로소프트 워드를 비롯한 여러 출판 소프트웨어를 비교해 보겠다.

타이포그래피

행 정돈

출판 소프트웨어의 타이포그래피 기능들 가운데 가장 중요한 것이 행 정돈(justification)이다. 흔히 생각하는 것과 달리 출판 도구들은 행 정돈에서 차이를 보여준다. 좋은 소프트웨어는 다음과 같은 결과를 만들어낸다.

  • 양끝 맞춤으로 정렬할 때, 문장 부호가 행의 처음에 놓이지 않는다.
  • 한 문단의 마지막 행이 한 단어 또는 한 글자로 끝나지 않는다.
  • 행의 끝에서 영어 단어가 하이프네이션 규칙에 따라 잘린다.
  • 행의 길이를 8 센티미터 이하로 줄였을 때 문단을 세로로 가로지르는 물줄기가 생기지 않는다.
  • 한글과 로마자에 서로 다른 폰트를 지정할 수 있다.
  • 한글과 로마자 사이의 간격을 조정할 수 있다.

매뉴얼이 다른 언어로 번역되었을 때 이 문제가 두드러진다. 독일어로 번역되었다면 독일어 하이프네이션 규칙이 적용되어야 한다. 한국어 버전 MS 워드는 오로지 영어와 한국어 타이포그래피만 구현할 수 있다. 이 문제를 회피하는 가장 손쉬운 방법은 왼끝 맞춤으로 문단을 정렬하는 것이다. 많은 언어에서 왼끝 맞춤이 해법이 된다.  그러나 오른쪽에서 왼쪽으로 쓰는 (right-to-left) 아랍어나, 띄어쓰기가 없으면서도 자유로운 줄 나눔(line break)을 허용하지 않는 태국어로 문서를 만들어야 할 때 워드 프로세서는 선택지에 포함될 수 없다.

판면 디자인

문서가 크게 세 부분으로 나뉜다.

  • 전문 (front matter)
  • 본문 (main matter)
  • 부속 (back matter)

전통적인 타이포그래피를 따르자면 각 부분에서 판면 디자인이 조금씩 달라진다. 예를 들면, 페이지 번호가 전문에서 로마자로, 본문에서 아라비아 숫자로 표기된다.  본문에서 장절 제목이 번호를 갖는 경우에도 서문에서는 번호를 갖지 않는다.  정보를 나타내는 여러 가지 표현 방법들이 있다.  그것들은 목록, 그림, 표, 또는 상자로서 판면에 배치된다. 어떤 표현 개체들이 사용될지는 내용에 따라 결정된다. 좋은 출판 소프트웨어는 사용자가 원하는 판면과 개체를 쉽게 구현하도록 도와준다. 넓게 설정된 바깥쪽 여백에 중요 정보를 담은 상자를 배치하는 디자인을 생각해 보자. 그것이 독자를 특정 정보에 주목시키기에—필수적이라고 할 수는 없어도—가장 효과적인 방법이라고 생각될 때, 현재 사용하는 출판 도구가 이를 만들어주지 못한다면 차선의 디자인을 구상해야 한다. 워드 프로세서가 사용자에게 허용하는 디자인은 제한적이다.

벡터 이미지

워드 프로세서가 EPS 파일 처리에서 신뢰성을 담보하지 못함을 여기에서 언급하지 않을 수 없다.

효율성

매뉴얼 제작에서 효율성은 타이포그래피 성능보다 오히려 더 중요한 문제일 수 있다. 상호참조를 만드는 것이 가능하지만 매우 수고스럽다면 사용자는  상호참조 만들기를 기피할 것이다. 무엇을 만드는 것이 가능하다는 것만으로는 충분하지 않다. 장애로 느끼지 않을 만큼 그런 작업을 쉽게 할 수 있어야 한다. 효율성을 높이는 방법은 서식 기능을 활용하는 것이다. 하나의 서식(style)은 그것이 적용되는 단어 또는 문단이 어떤 글꼴에 어떤 모양으로 표현될지 정의되어 있다. 제목 서식은 2.3과 같은 번호를 자동으로 붙여준다. 모든 출판 도구가 서식 기능을 제공한다. 좋은 출판 도구는 다음과 같은 기능들을 제공한다.

  • 어떤 서식의 속성이 바뀌었을 때 그로부터 파생된 서식들도 바뀐 속성을 갖는다.
  • 서식 사이의 논리적 관계를 이해한다. 예를 들어, “제목 1” 과 “제목 2” 서식이 연이어 왔을 때, 제목 1의 아래 간격 또는 제목 2의 위 간격이 무시된다.
  • 그림과 표도 서식으로서 다룰 수 있다.
  • 한 문서에 사용된 서식들을 다른 문서에 가져올 수 있다.

서식 기능에서 MS 워드와 어도비 인디자인을 비교하자면 인디자인이 더 많은 장점들을 갖고 있다. 그러나 이것만으로 인디자인이 더 생산적인 도구라고 말할 수 없다. 테크니컬 라이터가 직접 사용하기에 인디자인은 매우 버겁다.  인디자인 편집자를 두는 경우에 효율성을 따지는 셈법이 복잡해진다.

워드 프로세서를 제외한 출판 도구들이 여러 파일을 하나로 묶는 기능을 제공한다. 그 기능이 문서 작업에서 효율성을 크게 높인다. 이것의 유용성은 아무리 강조해도 지나치지 않다.

비용

워드 프로세서는 저렴하다. 그리고 다른 출판 도구들에 비해 기능이 적고 직관에 의지하여 익힐 수 있기 때문에 배우는 데에 오랜 시간이 걸리지 않는다. 반면 다른 출판 도구들은 구입하는 데에 그리고 익히는 데에 상당한 비용을 요구한다. 위지윔(What You See is What You Mean) 소프트웨어로 눈을 돌리면 (예외적으로 성능이 좋지 않은 프리웨어가 있지만) 훨씬 더 많은 비용이 든다. Arbortext를 비롯한 XML 출판 도구들이 이에 속한다. 여기에서 고려해야 할 것은 소프트웨어 자체의 가격이 아니다. 고가의 좋은 소프트웨어를 구입하는 것만으로 모든 문제가 저절로 해결되지 않는다. 그것을 잘 활용할 수 있는 인력이 필요하다. 그 비용이 높아진 생산성을 상회한다면 고가의 소프트웨어를 선택하는 것이 현명한 결정이 될 수 없다.

프레임메이커

프레임메이커는 기술 문서 제작을 목적으로 설계된 소프트웨어이다. 프레임메이커는 위에서 언급한 문제들 대부분을 적당히 다룰 수 있다. 만능의 이면에는 어정쩡함이 있다. MS 워드에 비하면 비싸고 인디자인에 비하면 타이포그래피 성능에서 신통치 않다. 그러나 효율성과 비용까지 고려하면 프레임메이커가 최적의 대안이 될 수 있다. 사실 프레임메이커는 가장 많이 사용되는 출판 도구이기도 하다.

2012 Technical Communication Industry Benchmarking Survey Summary

모든 기업을 대상으로 조사한다면 분명 워드 프로세서가 가장 많이 사용되는 도구일 것이다. 그러나 이름이 널리 알려진 기업들은 워드 프로세서를 좀처럼 사용하지 않는다. 워드 프로세서는 대외적으로 배포되는 공식 문서를 만들기에 미흡하다.

다음 글에서는 이 문제를 위지윔이라는 스펙트럼에서 살펴 보겠다.

Global Audience Analysis – A Unified Approach

From the outside, technical writing seems to only focus on the how – how to install an application on your computer, how to clean your new appliance and replace its components, how to use an API to let an app retrieve data – but, like journalists, technical writers also have to worry about the five Ws: who, what, where, when, and why. However, unlike reporters, the five Ws of technical writing are Who am I writing for?, What do they already know?, Where will they see this information?, When will this information be used?, and Why is this information important?

Answering these questions has become more difficult than ever. Audiences often include people from around the world with varying education levels, differing cultural values and sensitivities, and diverse usage environments. For these reasons, technical writers and UX designers must expand their research methods to include audiences from around the world. They must then use profiling techniques to approach their writing with these audiences in mind. This post introduces a holistic approach to research that combines top-down, bottom-up, and audience profiling to ensure that you and your writing team have all of the information required to reach your audience at your fingertips.

Top-down research

A good starting point for analyzing your audience is to use existing internal sources, such as your company’s marketing and sales teams, the analytics for your company site, and community forums for existing products. These resources help you identify the type of people that you’ll be writing for and the information that they’ll be interested in.

Your first stop should be the sales and marketing teams. These teams can provide a wide range of high-level information. Your sales team can provide ample information about existing clients and users, such as statistics on current users. In addition to this, the marketing team amasses large amounts of market research about the target demographic, that is, the users, of your product or service. These teams may even produce internal case studies detailing specific examples of customers using your product.

Your sales and marketing teams should be able to provide the following general information about your audience:

  • Gender
  • Age
  • Education level
  • Monthly and annual income
  • Occupation/profession
  • Marital status
  • Nationality
  • Social class
  • Population size
  • Region

This demographic information offers a tremendous amount of insight into your audience. However, it only addresses the first two Ws: Who am I writing for? and What do they already know? This information is invaluable, but addressing the other three Ws requires bottom-up analysis in the form of focus groups, surveys, and support system reviews.

Bottom-up research

Your top-down research provides you with a general idea of who will be using your documentation. However, a bottom-up analysis – that is, an analysis that includes information gathered directly from your audience – is necessary to establish where your audience will see the information, when they will seek out this information, and why they sought this information in the first place. In most cases, a bottom-up analysis takes the form of focus group interviews, user surveys, and reviews of support system information or a combination of these three tactics.

Focus group interviews can provide deep insight into how and why your audience uses your product or service. However, they are also the most expensive method of finding out about your audience. Often, a good idea is to piggyback on a focus group convened by the sales or marketing teams in your company, as your audience will also be their target demographic.

Your focus group should include people that fit the demographic profile identified in your top-level analysis. When you’re writing for a global audience, this means that you may need to conduct multiple focus group sessions in various countries. This can be a costly, but beneficial, exercise, especially when entering a new market abroad. However, if the cost is too great, then you should strive to assemble a multicultural focus group within your own country.

Focus groups can help you gain more insight into the following:

  • Where users use documentation
  • What motivates your users to use your documentation
  • Why users use (or don’t use) your documentation

User surveys are another method of finding out about your audience. Although not as costly as focus group interviews, user surveys still require a certain amount of upfront investment in their creation and a lot of work to tease out relevant results from the mountain of data that you accumulate. Furthermore, user surveys tend to add a filter to your audience – that is, only a certain portion of your demographic is likely to fill out a survey.

The value of surveys, however, is that they are relatively inexpensive to administer compared to focus groups and allow you to compile answers to targeted questions comparatively quickly. The survey method you use largely depends on how established your company is in the target region. If you already have existing customers or clients in the target region, then they may be willing to fill out a short survey. If your products have generated some interest in the region, then adding a call to action that directs visitors to your website may be the way to go. Finally, if your brand is new to the region, then you may want to consider hiring a market research company to make sure that your survey reaches your target demographic.

Users surveys can help you answer the following:

  • Where users use the product or documentation
  • When users use the product or documentation
  • Who do the users trust for information

Finally, support systems, such as Zendesk, or even sales sites that feature reviews, such as Amazon, allow you to gain some insight into how your audience uses your product and the aspects of your product that they find most troublesome. Like user surveys, support system research requires a substantial investment in labor and only the portion of your audience predisposed to making comments will do so. Nevertheless, a support system review offers the quickest way to receive direct input from users regarding the success or failure of your documentation.

Because the content focuses on the problems users encounter, support system reviews offer only a limited window through which to get to know your audience. But, as a technical writer, you strive to minimize these problems, so support systems provide excellent insight into when and where your audience requires information as well as the features that they need the most information about. Although valuable, this information is insufficient to create an audience profile, so a support system review should be supplemented by one of the other methods of bottom-up analysis.

Audience Profiles

The information gathered from your top-down and bottom-up analysis is invaluable, but you undoubtedly have mountains of it. Staring at spreadsheets full of demographic information, survey responses, and customer complaints quickly gets boring. To combat this, writers use audience profiles to put a real face on their audience.

Audience profiles, sometimes referred to as reader profiles, compile your top-down and bottom-up research into digestible descriptions of audience members. These profiles usually take the form of a narrative, but a CV-inspired style is also popular. Less popular, but still effective, is the collage-style audience profile.

Narrative profiles leverage what you already do well – write – to describe an audience members in a manner similar to that found in narrative prose. Many writers perform similar exercises when coming up for characters for fiction. Narrative profiles often contain greater detail and provide a more natural way to read than the CV or collage models. However, narrative profiles are also more difficult to scan, so you may find yourself rereading the same description over and over to confirm details as you write. For this reason, narrative profiles often include a photograph of the fictional audience members procured from a stock image site.

CV-style profiles allow you to easily locate important information at the expense of readability. These profiles consist of bullet points grouped under various headings, such as work experience, family life, and hobbies and interests. Like narrative profiles, CV-style profiles often include a picture so that the writer can identify with the face of the audience. The bullet points allow you to quickly scan the page for relevant information when writing. However, because the information is segmented in bullet points, it may be more difficult to paint a portrait of the audience member in your mind’s eye when reading the profile.

Collage-style profiles have fallen out of favor in professional writing, perhaps because they make your cubicle resemble a teenager’s bedroom, but they can still be as effective as the other profile methods. A collage profile usually consists of pictures of the fictional audience member and items related to their profession, interests, hobbies, and family. For example, a profile of an audience member may include pictures of schematic drawings, the Indiana Colts playing football, wakeboarding, and young children. These images may be supplemented by quotes from the audience member, such as “Why can’t they just print the instructions on the damned thing.” Collage profiles offer writers a refreshing break from reading and writing but require the writer to recall the motivation for including a picture or quote when writing it and require substantial explanation when handing off the project to another writer.

Conclusion

Whichever profile style you decide on, you’ll probably want to create at least one profile for each target country so that, as you write, you can ask yourself “Would Pornchai from Thailand find this easy to read?” or “Would Samadhi from Sri Lanka look for this information here?” In short, you can try to approach your writing through the eyes of your audience. Doing so will greatly increase the effectiveness of your writing and add a necessary direction to your voice. But remember, a good profile requires the right kind of research, so the top-down and bottom-up research steps are incredibly important. Performing all of the tasks described in this post with the end goal in mind will ensure that your text is accessible to your entire audience.