기록쟁이의 기술 놀이터

좋은 기술 문서 작성하기 (3)

임숩니 — Fri, 4 Jul 2025 17:39:09 +0900

문서 개발 프로세스 & 시각 자료 활용

1. 문서 개발 프로세스

초안 작성
동료 리뷰
사용자 피드백 반영
편집 및 최종 검수

2. 체크리스트 기반 품질 점검

책에서 QTI 평가 체크리스트 제공 (문서 자가 진단용)

3. 시각 자료 활용 팁

복잡한 정보를 표, 목록, 도표 등으로 시각화
시각 요소는 설명과 함께 제공해야 효과적
인터페이스 스크린샷, 흐름도 등도 포함 가능

좋은 기술 문서 작성하기 (2)

임숩니 — Tue, 10 Jun 2025 10:03:54 +0900

독자 중심 문서 작성 전략

1. 독자 중심 접근

누가 읽는가? (초보/전문가/개발자 등)
무엇을 하려는가? (문제 해결, 설치, 학습 등)

2. 구성 전략

목적별 구조화: FAQ, 단계별 가이드, 경고/팁 구분
헤드라인, 목차, 색인 활용
시나리오 기반 예제 제시

3. 문체 원칙

능동태 선호, 모호한 표현 배제
문장 당 핵심 1개, 단문 선호
표준 용어와 형식 사용

좋은 기술문서 작성하기(1)

임숩니 — Thu, 5 Jun 2025 15:11:50 +0900

좋은 기술 문서의 9가지 기준

정확성 – 틀림없이 올바른 정보
완전성 – 독자에게 필요한 정보 모두 포함
명확성 – 이해하기 쉬운 표현
간결성 – 불필요한 단어 제거
일관성 – 용어와 표현 통일
유용성 – 독자 상황에 실제 도움
조직화 – 논리적인 정보 흐름
시각적 명료성 – 목록, 표 등 시각 요소 활용
접근성 – 원하는 정보에 쉽게 접근 가능

매뉴얼 평가 (3) - 전체 매뉴얼 평가

임숩니 — Mon, 24 Feb 2025 12:37:59 +0900

1. 사용성

1) 효용성(매뉴얼만으로 제품 사용에 문제가 없는가?)

2) 편의성(제품 사용에 필요한 정보를 제공하는가?)

3) 개선 요구(제품 사용을 위해 개선이 필요한가?)

2. 구성 전략

1) 일람성: 문서 번호, 목차, 표/그림 목차, 서문, 매뉴얼 사용 안내, 작동 원리 소개, 절차 진술, 예제, 에러/문제 해결, 용어 정리, 출처 정보, 탐색 기능, 색인, 검색 기능, 페이지 표시

2) 사용성: 설치 및 제거, GUI 요소 소개, 로그인/아웃, 기능 접근 및 나가기, 조작 수행성, 문제 시 조작 취소 및 재시작, 머리글/바닥글

3) 목차: 서문과 본문 페이지 표기, 장/절 표기, 장/절 시각 효과, 독자 지향 순서로 구성

4) 독자 지향 절차: 순서도, 개념 설명, 메뉴 트리, 필요 시 별도 정보 소개, 선행 진술문, 도입부

5) 제품 사용 사례(Use Case)

6) 안전 문구 및 참고 사항

7) 검색성: 검색 진술문, 상호 참조, 목차, 색인, 용어 정의, 온라인 검색 기능

3. 정보 구조

1) 매뉴얼 유형별 취지에 맞는 구조

2) 취지에 맞는 토픽 구조

3) 일관된 절차 진술

4) 절차 진술의 내용: 제목, 준비 정보, 절차 진술, 상세 절차 진술, 조건별 진술, 시각 정보 포함, 절차 완료 진술

5) 진술의 명확성과 완결성

4. 표기 및 시각 효과

- 가독성과 시인성: 목차/페이지 표시, 일관된 그래픽 규칙, 텍스트와 그래픽 연관성, 태스크의 시각 요소, 일관된 신호어 표현, 표기 규칙, 색상 컨셉

5. 문체 및 어법

1) 일관된 문체

2) 표기 규정: 괄호, 날짜, 인용부호, 구두법, 수학 연산자, 숫자, 열거, 약어, 화폐, 전화번호, 대시, 폰트, 명칭과 버튼/아이콘 표기, 다단계 메뉴 선택 표기

3) 철자법

4) 띄어쓰기

* 해당 콘텐츠는 한겨레 교육 최형선 선생님의 Technical Writing과 기술 번역 강의내용을 토대로 학습 및 기록용으로 작성되었습니다. 모든 강의 내용이 포함되지 않았기에 더 자세한 내용 및 자료를 원하시는 경우 해당 강의 수강을 추천드립니다.

매뉴얼 평가 (2) - 평가 방법

임숩니 — Fri, 21 Feb 2025 10:05:14 +0900

1. 평가자 선정/평가 배점

- 대상 사용자와 동일한 복수의 평가자 선정(3명 이상)

- 평가자가 5명 이상인 경우 분야별 최고점과 최저점을 제외시킴

- 중요도에 따라 가중치를 부여할 수 있음

- 분야별 최고점과 최저점 사이의 격차가 너무 크면 모여서 점수를 조정함

2. 사용성 테스트

- 피험자는 매뉴얼을 읽고 제품을 사용

- 피험자의 행동을 관찰하고 기록함(비디오 촬영을 하는 경우도 있음)

- 테스트 종료 후 시간이 걸린 부분, 조작을 잘못한 부분, 조언자에게 도움을 요청한 부분 등에 대해 청취

3. 명료성 평가

- Fog Index 측정: Robert Gunning이 개발

- 공식: (문장의 평균 단어 수 + 어려운 단어 백분율) x 0.4

- 이상적인 명료성 수치는 8또는 9

- 15가 넘어가면 매뉴얼을 다시 작성해야 함

* 해당 콘텐츠는 한겨레 교육 최형선 선생님의 Technical Writing과 기술 번역 강의내용을 토대로 학습 및 기록용으로 작성되었습니다. 모든 강의 내용이 포함되지 않았기에 더 자세한 내용 및 자료를 원하시는 경우 해당 강의 수강을 추천드립니다.

매뉴얼 평가 (1) - 매뉴얼 평가란?

임숩니 — Wed, 19 Feb 2025 09:38:02 +0900

1. 훌륭한 매뉴얼의 특징

- 이해하기 쉽다: 태스크 지향 • 정확성 • 완결성

- 사용하기 쉽다: 명확성 • 구체적(예제 중심) • 훌륭한 스타일

- 검색하기 쉽다: 훌륭한 구성 • 원위치 탐색성 • 시각적 효과

제품 사용성은 매뉴얼 품질에 기인: 매뉴얼 평가 공정이 생겨난 이유

2. 매뉴얼 역할 증대

- 제품 조작 방법의 복잡성

- 전문 지식 없는 일반 소비자의 증가

- 혁신적인 기능이나 조작 방법 등장

3. 평가 방법

- 리뷰에 의한 평가: 다시 읽으면서 내용과 실제 제품 기능에 차이가 없는지 확인

- 사용성 테스트에 의한 평가: 매뉴얼을 읽으면서 제품을 조작해 보는 테스트

* 해당 콘텐츠는 한겨레 교육 최형선 선생님의 Technical Writing과 기술 번역 강의내용을 토대로 학습 및 기록용으로 작성되었습니다. 모든 강의 내용이 포함되지 않았기에 더 자세한 내용 및 자료를 원하시는 경우 해당 강의 수강을 추천드립니다.

전자 매뉴얼 제작 (5) - 관련 법령_Barrier-free

임숩니 — Tue, 18 Feb 2025 09:46:55 +0900

1. Barrier-free Universal Design

- 고령자나 장애인들의 불편을 감안해서 도와주고 사회적 불이익을 경감하는 활동

- 장벽 없는 매뉴얼을 만들려면 장애를 가진 사람과 소통하려는 노력이 가미된 매뉴얼이 필요

2. Barrier-free 매뉴얼

1) 청각 보조: 낭독해주거나 읽어주기 기능 추가

2) 촉각 보조: 점자 매뉴얼 제공

3) 시각 보조: 오디오를 대신해 동시에 텍스트 제공

4) 기타: 마우스 조작이 불가한 경우 키보드 조작 제공, 약시 사용자를 위해 큰 활자 기능 제공

- 링크는 ‘여기를 클릭’이라고 하지 말고 정식 명칭을 사용

- 링크 버튼에는 링크 주소를 알려주는 기능 제공

- 표지 정보를 오디오 브라우저로도 읽게 할 수 있음

- 오디오 정보는 텍스트로도 읽을 수 있게 해야 함

* 해당 콘텐츠는 한겨레 교육 최형선 선생님의 Technical Writing과 기술 번역 강의내용을 토대로 학습 및 기록용으로 작성되었습니다. 모든 강의 내용이 포함되지 않았기에 더 자세한 내용 및 자료를 원하시는 경우 해당 강의 수강을 추천드립니다.

전자 매뉴얼 제작 (4) - 제작 툴

임숩니 — Mon, 17 Feb 2025 09:41:08 +0900

1. 소재 작성 툴

- 문자 입력 툴

- 드로잉 툴

- 포토 리터치 툴

2. 저작 툴

- Director, Flash, help Workshop, HTML HelpWorkshop, RoboHelp, MedCap Flare 등

3. 데이터 변환 및 생성 툴

- Acrobat 등

* 해당 콘텐츠는 한겨레 교육 최형선 선생님의 Technical Writing과 기술 번역 강의내용을 토대로 학습 및 기록용으로 작성되었습니다. 모든 강의 내용이 포함되지 않았기에 더 자세한 내용 및 자료를 원하시는 경우 해당 강의 수강을 추천드립니다.

전자 매뉴얼 제작 (3) - 검교정

임숩니 — Thu, 13 Feb 2025 09:48:50 +0900

- 문서나 글의 오류를 찾아내고 수정하는 과정

1. 목적

- 내용의 부적절성/부정확성/비통일성 여부 확인

- 종이 매뉴얼과의 일치성 확인

- 디버깅

- 작동 확인

2. 교정

- 디버그를 통해 문제점 수정; 용어와 표현 불일치도 및 종이 매뉴얼과의 일치성 확인

3. 검정

- 기록 순서가 제품 작동과 일치하는지 확인

- 메시지나 화면이 서술 내용과 일치하는지 확인

- 기능 명, 커맨드 명이 기술 내용과 일치하는지 확인

* 해당 콘텐츠는 한겨레 교육 최형선 선생님의 Technical Writing과 기술 번역 강의내용을 토대로 학습 및 기록용으로 작성되었습니다. 모든 강의 내용이 포함되지 않았기에 더 자세한 내용 및 자료를 원하시는 경우 해당 강의 수강을 추천드립니다.

전자 매뉴얼 제작 (2) - 제작 공정

임숩니 — Wed, 12 Feb 2025 09:52:06 +0900

[기획/ 구성/ 표현 설계] -> [시나리오 작성] -> [소재 수집] -> [디지털 데이터 처리] -> [저작] -> [패키지화]

1. 기획/구성/표현 설계

- 기획서에 포함되는 내용은 다음과 같다.

1) 지원 OS와 버전

2) 데이터 형식: HTML(범용적 문서 형태를 지니며 인터넷에서 사용), XML(콘텐츠와 스타일시트를 통해 다양한 형태 제공 가능), PDF(주로 인쇄 데이터를 변환; 최근에는 시뮬레이션도 추가 가능), 실행 파일(어플리케이션 형식), Winhelp(윈도우 헬프 형식), HTML 헬프(윈도우 HTML 헬프 형식), Web help(자바 스크립트를 사용해 윈도우와 맥에서 사용 가능), Java help(자바 프로그램이 실행되는 모든 환경에서 사용 가능)

3) 표현 설계: 폰트는 고딕체를 사용하고 글자 크기는 상대값으로 지정하며 중요 정보는 화면 왼쪽에 배치함

4) 동영상/음향 포함: 동영상(전자 매뉴얼만의 독특한 요소로 레이아웃/디자인 뿐 아니라 시간의 흐름도 고려해야 함), 음향(청각 특징과 시각 효과를 고려)

2. 시나리오 작성

- 시나리오는 스토리 효과를 기대할 수 있을 때 긴요

- 텍스트/영상/오디오 외에 콘텐츠 구조화 능력이 필요

- 사용자 심리나 생리적 반응에 대한 이해도 필요

- 음향이나 동영상에서는 주제를 마지막에 위치

- 콘텐츠 모듈화/블록화/연계

- 대화형 표현

- 다양한 콘텐츠 접근 경로와 방법 기획

- 읽기 진행 안내나 참고 기능 추가

- 사용자가 원하는 순서를 연출

3. 소재 수집

1) 문서

2) 정지 화면: 사진(필름 사진은 변환), 일러스트

3) 동영상: 영화나 애니메이션(데이터가 커서 주의가 필요)

4) 음향: 목소리나 음악 등이 소리(아날로그는 디지털로 변환)

4. 디지털 데이터 처리

1) 플레인 텍스트: 텍스트로 문자 코드와 제어 코드로 구성

2) JPG: 정지 화면 소재로 파일 압축이 가능; 복사할 때마다 품질 저하

3) BMP: 윈도우에서 주로 사용하는 정지 화면 형식

4) PICT: 매킨토시에서 주로 사용하는 정지 화면 형식

5) TIFF: 프로그램 간 래스터 이미지를 교환할 때 사용; 의료기 3차원 이미지에 사용

6) GIF: 파일 크기가 작아 인터넷 배포로 적합한 정지/동영상 소재 형식

7) PNG: GIF의 특허 문제를 피하기 위해 제시; 최근 JPG대신 많이 사용

8) SWF: MS 플래시용 동영상 형식; 인터넷 배포 콘텐츠에 주로 사용

9) WAV: 윈도우에서 주로 사용하는 오디오 형식

10) MP3: 고음질 압축이 가능한 오디오 형식; WAV에 비해 데이터 크기 작음

11) RTF: 텍스트와 정지 화면의 복합 형식으로 Winhelp에 사용

12) EPS: 텍스트와 정지 화면의 복합 형식으로 DTP나 드로잉 툴에서 제작; 전자매뉴얼에서는 사용하지 않음

13) AVI: 동영상과 오디오의 복합 형식

14) MPEG: 동영상과 오디오의 복합 형식으로 여러 변형이 존재

15) QuickTime: 동영상과 오디오뿐 아니라 정지 화면이나 텍스트 소재로 복합 사용

16) 처리 가능한 데이터 형식 변환(CAD 변환, 디지털 데이터로 변환)

17) DTP 데이터를 PDF로 변환

18) 보안 키 설정

19) 변환 시 툴 버전 일치화 필요

5. 저작/ 오서링

- 처리한 데이터를 보조하는 자동화 저작 툴을 사용해 시나리오대로 작성

6. 패키지화

- 오서링 완료 후 마스터 카피 제작

- 사용 조건에 따라 마스터 카피를 최종 배포 형태로 패키징

- CD-ROM 삽입 또는 서버 저장

* 해당 콘텐츠는 한겨레 교육 최형선 선생님의 Technical Writing과 기술 번역 강의내용을 토대로 학습 및 기록용으로 작성되었습니다. 모든 강의 내용이 포함되지 않았기에 더 자세한 내용 및 자료를 원하시는 경우 해당 강의 수강을 추천드립니다.