테크니컬라이팅이란?

국내에도 테크니컬 라이터라는 직업과 테크니컬 라이팅이라는 업무가 존재는 하지만 많지 않고 실제로 팀 단위로 진행되거나 전문화되어 체계가 잡혀있는 경우가 많지 않은 것 같다.

인터넷에서 검색을 하다보면 많은 테크니컬 라이팅 기술이 나오는데 대부분 외국의 사례를 가져와서 번역한 내용이 많고 나또한 그런 글들 중 중요하다고 생각하는 핵심 내용만 정리하는 목적으로 글을 써본다.

 

 

 

 

 

문서의 종류 구분

문서를 목적에 따라서 분리하여 작성하기 위한 구분

 

1. Tutorial (튜토리얼)

:초보자를 학습위주로, 사용자가 기본적인 기술을 익힐 수 있도록 합니다.

2. How-to guide (How-To가이드)

:정해진 결과를 달성하기 위해서 사용자가 기본적인 지식을 가지고 있다고 가정하고 문제 해결방법을 알도록 합니다.

3. Explanation (설명)

:배경이나 주가적인 세부 내용에 대한 이해를 돕도록 합니다.

4. Technical reference (기술참조)

정보를 기본으로 내용을 정확하고 완전하게 설명 합니다. (ex API reference)

 

 

 

 

 

미니멀 리스트 4가지 지침

문서로 사용자를 능숙하게 만드는 가장 좋은 방법

 

1.행동 중심의 접근법을 선택

2.작업하는 영역에서 사용하는 도구를 지정

3.오류 인식과 복구를 도와주기

4.다양한 청중의 요구사항과 성향을 최대한 맞추기 위해서 읽고, 공부하고, 배치하기

 

 

 

 

 

구성주의 4가지 원칙

학습은 학습자가 자신의 지식 기반을 바탕으로 새로운 아이디어를 구성하는 적극적인 과정

 

1. 독자가 스스로 원칙을 찾을 수 있도록 독자를 독려

2. 현재 독자 수준에 적합한 형식으로 정보를 번형

3. 나선현 자료 구성

4. 사용자들이 '실제로 시도하고', '어떤 일이 일어났는지 확인하고', '스스로 탐구'할 수 있도록

 

 

 

 

 

메타 라이팅 피하기

글쓰기를 위한 글을 쓰지 않기 (문서를 이용하는 당사자는 독자와 저자)

 

 

 

 

 

기술 부채란?

프로젝트 내에서 어떤 문제를 해결할 때 장기적인 관점에서 기획 및 검토하지 않고 임시적인 방편으로 그 문제를 해결하여, 그로 인해 나중에 큰 비용이 발생할 수 있는 요소

 

기술 부채 해결 방법

1. 수시로, 또는 주기적으로 프로젝트를 검토(audit)하는 시간을 가질 것

2. 스타일 가이드나 탬플릿을 만들고 그것을 계속 업데이트하려고 노력할 것

3. 사용자의 피드백을 받고 수시로 반영할 것

4. Definition of Done을 정의 할 것(DOD는 문서 작업의 퀄리티를 보장하는 도구로 사용될 수 있음)

 

 

 

 

 

릴리즈 노트란?

소프트웨어 배포와 함께 게시되는 점 목록의 글로 Bug fixes, New farutres, Known issues로 구성되는 문서

 

릴리즈 노트의 구성 요소

1. Bug fixes : 지속적으로 사용자에게 불편을 주던 오류나 버그 따위를 고친 것

2. Features : 지속적 또는 오랫동안 사용자가 원하거나 요청한 것을 추가한 것

3. Known issues : 가끔 또는 자주 발생하는 오류나 불편사항(아직 고치지 못했거나 고치는 방법을 모름)이 있음을 알리는 것, 또 그것을 언젠가는 고칠 것임을 예고한 것

 

릴리즈 노트 작성 노하우

1. 'Expand out and Simplify'

2. System이나 모듈이 아닌 사용자의 관점에서 쓰도록 권고

3. 유머나 개성이 드러나는 방식을 지양

 

릴리즈 노트 탬플릿

~을 할 수 있음, ~이 가능해짐	Bug fixes나 Feature 항목에 사용할 수 있는 패턴
Z일 때 Y하지 않고 X하게 됨	과거(Y)와 현재(X)의 차이를 설명하고 맥락(Z)을 나타낼 때 좋은 패턴
Z를 하기 위해 Y대신 X를 해야 함	과거(Y) 대신 현재(X)를 수행하여 목표(Z)를 이룰 수 있도록 가이드 할 때 좋은 패턴

 

 

 

 

 

참고

https://mkaz.blog/misc/notes-on-technical-writing/

zianlog.tistory.com/entry/%EB%B2%88%EC%97%AD-%ED%85%8C%ED%81%AC%EB%8B%88%EC%BB%AC-%EB%9D%BC%EC%9D%B4%ED%8C%85%EC%9D%84-%EC%9C%84%ED%95%9C-%EC%B0%B8%EA%B3%A0%EC%9E%90%EB%A3%8C

engineering.linecorp.com/ko/blog/write-the-docs-prague-2018-recap/

• 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