[번역] 테크니컬 라이팅을 위한 참고자료

원문은 Wordpress를 담당하는 Automattic의 엔지니어인 Marcus Kazmierczak의 포스트 'Notes on Technical Writing'(https://mkaz.blog/misc/notes-on-technical-writing/)입니다. 발 번역, 의역이 다수 포함되어 있습니다. 번역에 대한 수정/보완 제안은 언제든지 환영합니다. 번역 포스팅이 문제가 될 경우 언제든 포스팅을 삭제 하겠습니다.

---

작년 한 해 동안 Wordpress에 대한 문서작업을 수행했습니다. 나는 개발자들이 새로운 플랫폼으로 전환하는 것을 돕기 위해 출시 전후로 Freeze(역자 주: S/W 출시 전후로 더 이상의 코드 변경을 중단하는 등의 작업)에 참여하기 시작했습니다. 그 과정에서 나는 스스로가 문서 작성하는 것을 즐기고 있으며, 교육을 통해 사람들을 돕는 것이 스스로에 대한 보상이 된다는 것을 깨닫게 되었습니다. 비록 문서작성이 내 업무의 주요한 부분은 아니지만, 나는 계속 문서작성에 시간을 들여왔고 또 프로젝트에 기여해 왔습니다.

이번 기회를 통해 나는 테크니컬 라이팅과 문서화에 대한 여러 자료들을 읽었습니다. 여기에는 나 자신의 기록도 있고 나중에 기억을 되뇌는데 도움이 되거나 지금 글쓰기에 대한 생각을 정리하는데 도움이 되는 내용들이 있습니다.

원칙

아래는 글을 쓸 때 지켜야 할 원칙들입니다.

• 테크니컬 라이팅의 목적은 사람들이 빠르게, 가능한 효율적으로 업무를 수행할 수 있도록 돕는 데 있습니다.
• 사람들은 무언가 '하면서' 배우고 보여주지만 말하지 않는 것을 선호합니다.
• 사람들이 첫 성공의 경험을 빠르게 얻도록 하십시오
• 다양한 문서의 종류가 존재한다는 것을 기억하십시오
• 단순하고 일반적인 언어로 글을 작성하십시오 

팁

• 독자가 누구인지, 글의 목적이 무엇인지 기억하십시오
• 가장 중요한 정보는 처음에 작성합니다
• Bullet List(글머리 기호 목록)을 사용하십시오
• 하나의 단락에는 하나의 아이디어만 담으십시오
• 수정하고, 수정하고, 수정하세요

메타 라이팅 피하기

글쓰기를 위한 글을 쓰지 마세요. 글 자체로는 아무것도 아닙니다. 문서를 이용하는 당사자는 저자와 독자입니다.

무엇을 이야기할지 설명할 필요 없습니다. 직접적으로 알려주세요

• 나쁜 예 : 이 챕터에서는 왜 어떤 이름은 인기 있고, 어떤 이름은 인기가 없는지에 대해 논의합니다.
• 좋은 예 : 무엇이 인기 있는 이름을 만드는가?

글의 내용 안에서 섹션이나 문단을 언급하지 마세요

• 나쁜 예 : 앞 섹션에 대해 요약하면...
• 좋은 예 : 정리하면...

독자에게 엄청나게 복잡하다고 이야기하거나 반대로 간단하다고 정의하지 마십시오. 독자가 스스로 쉬운지 어려운지 스스로 판단하게 될 것입니다.

미니멀리스트 지침

John M. Carroll과 그의 동료는 IBM에서 '사용자를 능숙하게 만드는 가장 좋은 방법'에 대한 분석 문서를 만드는데 지원했습니다. 1980년대에 그들은 워드프로세서를 처음 사용하는 사람들에게 무엇인가 소개해야 한다고 전제하여 미니멀리스트 접근법을 개발하였으며, 결국 IBM Displaywriter를 위한 '오퍼레이터 교육 매뉴얼'을 훌륭하게 완성하였습니다.

미니멀리스트를 위한 4가지 지침

• 행동 중심의 접근법을 선택하시시오. 사람들은 일반적으로 '무언가 하는 것'을 원합니다. 이 원칙은 사용자 중심의 미니멀리즘 본성을 반영한 것입니다.
• 작업하는 영역에서 사용하는 도구를 지정하십시오. 도구는 목적을 위한 수단입니다. 이 원칙은 디자이너가 사용자들을 위한 의미 있는 교육 작업들을 선택하도록 합니다. 
• 오류 인식과 복구를 도와주십시오. 사람은 실수를 합니다. 실수를 해결하는 데 있어 사용자의 역량을 높이고 편안하도록 하는 여러 가지 방법이 있습니다. 
• 읽고, 공부하고, 배치하십시오. 디자이너들은 가능하면 다양한 청중의 요구사항과 성향을 최대한 맞춰야 합니다. 이 원칙은 사용자 중심의 미니멀리즘 본성을 반영한 것입니다.

네덜란드 Twente 대학 교육공학과의 '미니멀리스트 지침'을 자세히 읽어보세요

구성주의

미국의 심리학자 Jerome Bruner는 인간 인지 심리학을 공부했습니다. Bruner가 연주한 주요 주제는 '학습은 학습자가 자신의 지식 기반을 바탕으로 새로운 아이디어를 구성하는 적극적인 과정'이라는 것입니다. 이 구성주의 원칙을 문서작성에 적용해 보면:

• 독자가 스스로 원칙을 찾을 수 있도록 독자를 독려하십시오
• 현재 독자 수준에 적합한 형식으로 정보를 변형하십시오
• 나선형인 자료 구성을 통해 지속적으로 그들이 배운 지식 위에 새로운 지식을 구성할 수 있도록 하십시오
• 활성화된 대화에 참여하여 사용자들이 '실제로 시도하고', '어떤 일이 일어났는지 확인하고', '스스로 탐구' 할 수 있도록 하십시오

브루너와 구성자 이론에 대해 더 읽어보세요

문서의 종류

Daniele Procida는 하나가 아닌 (적어도) 네 가지 종류의 문서가 존재한다는 내용으로 '아무도 알려주지 않는 문서화'라는 글을 썼습니다.

• 튜토리얼 : 튜토리얼은 초보자를 학습 위주로, 사용자가 기본적인 자신감과 기술을 익힐 수 있도록 합니다. 튜토리얼은 지식이나 언어를 가정하지 않고 배우는 내용에 대해 어떤 질문을 할지 모르는 초보자를 대상으로 합니다.
• How-To가이드 : How-To가이드 또는 FAQ는 사용자가 정해진 결과를 달성하도록 하는데 목적이 있습니다. How-To가이드는 사용자가 기본적인 지식과 언어를 가지고 있다고 가정하고 어떻게 특정한 문제를 해결할지를 알도록 합니다. 
• 설명 : 설명이나 오버뷰 문서는 배경이나 추가적인 세부 내용에 대한 이해를 돕도록 합니다.
• 참조 안내(Reference Guide): 참고 안내는 정보를 기반으로 내용을 정확하고 완전하게 설명합니다. API문서와 같은 것들이 참조 안내 문서의 한 예입니다. 

참고 문서

• On Writing Well (book) The classic guide to writing non-fiction by William Zinsser.
• Basic Writing Tips an article by Andrew Etter
• Wordiness: Danger Signals (2 page pdf) by Margaret Procter, University of Toronto
• Writing is Thinking by Sally Kerrigan, A List Apart
• Writing is Thinking, by Steph Smith
• Tips on Writing a Great Science Paper from Cormac McCarthy
• Microsoft Writing Style Guide