단계별 소프트웨어 안내를 명확하게 작성하는 방법

명확한 소프트웨어 안내는 독자가 안내를 의식하지 않고 작업을 끝내게 합니다. 불필요한 단어, 모호한 레이블, 여러 동작을 묶은 단계는 독자를 멈추게 하고 다시 읽게 만듭니다.

이 글은 가장 중요한 작성 규칙을 예제와 함께 설명하고, Mac의 Temposhot에서 가이드를 만들 때 이 규칙을 적용하는 방법을 다룹니다.

완료 결과를 하나로 정합니다

결과를 한 문장으로 먼저 씁니다. 독자가 화면을 보고 맞는지 아닌지 판단할 수 있어야 합니다. 예: "The invoice is sent to the customer and marked Sent." 이 문장이 가이드의 제목이자 마지막 단계가 됩니다.

결과를 하나로 쓸 수 없다면 안내가 둘 이상의 작업을 다루고 있는 것입니다. 이 경우 작업을 나눕니다. "send an invoice"를 검색한 독자는 "create a customer" 단계를 넘겨 가며 읽고 싶어 하지 않습니다.

첫 스크린샷을 찍기 전에 결과를 씁니다. 캡처한 뒤에 쓴 결과는 작성자가 우연히 누른 모든 클릭을 설명하기 쉽습니다. 먼저 쓴 결과가 가이드에 들어갈 클릭을 정합니다. 올바른 페이지에 도달하려고 메뉴를 여는 것처럼 화면 사이를 이동하기만 하는 클릭은, 목적지를 가리키는 레이블 하나로 대체할 수 있는 경우가 많습니다.

한 작업에 역할이 둘 필요하면 결과가 하나씩 있는 가이드를 두 개 작성합니다. 송장을 승인하는 사람을 위한 가이드와 송장을 발송하는 사람을 위한 가이드는 시작점과 확인 항목이 다릅니다. 두 역할을 하나로 합치면 모든 독자가 자신과 무관한 부분을 건너뛰어야 합니다.

모호한 결과와 확인 가능한 결과

결과는 독자가 화면을 보고 예 또는 아니요로 답할 수 있을 때 확인 가능합니다. 아래 표는 같은 작업을 두 방식으로 쓴 것을 비교합니다.

확인 가능한 버전은 안내의 길이도 정합니다. 화면에 보이는 상태로 끝나는 가이드는 자연스러운 마지막 단계가 있으므로, 첫 문단을 반복하는 맺음말을 덧붙일 필요가 없습니다.

각 단계를 동작으로 시작합니다

독자는 동사를 찾으며 읽습니다. 동사를 문장 앞에 둡니다.

약한 표현	명확한 표현
The Settings menu should now be opened.	Open Settings.
Next, you will want to click on Save.	Select Save.
In the top-right corner there is a Share button.	Select Share in the top-right corner.
Make sure that notifications are turned off.	Turn off Notifications.

짧은 동사 목록을 정하고 일관되게 씁니다. 목록은 Open, Select, Choose, Enter, Turn on, Turn off, Drag입니다. "Click"은 마우스 사용자에게는 통하지만 키보드와 터치 사용자에게는 통하지 않으므로, 많은 스타일 가이드가 "Select"를 권장합니다.

모든 단계에 명령형을 사용합니다. "Select Save"와 "Open Settings"는 독자가 지금 해야 할 일을 알려 줍니다. "You should select Save"는 독자가 행동하기 전에 걷어내야 하는 문장을 더합니다. 단계 끝의 결과 문장도 같은 규칙을 따르며, 화면에 무엇이 표시되는지 씁니다. 예: "The banner shows Changes saved."

컨트롤 종류마다 동사 하나

동사 목록은 동사마다 컨트롤 종류 하나에 대응할 때만 작동합니다. "Choose"를 본 독자는 목록이나 메뉴를 예상하고, "Select"를 본 독자는 버튼이나 링크를 예상합니다. 아래 체크리스트는 동사마다 규칙 하나를 제시합니다.

목록에 없는 컨트롤은 위치와 레이블로 설명합니다. 선택기를 여는 컨트롤은 "Choose", 프로세스를 시작하는 컨트롤은 "Select"로 씁니다. 동사 목록은 짧게 유지합니다. 동사가 하나 늘 때마다 작성자가 기억해야 할 규칙이 하나 늘어납니다.

정확한 인터페이스 레이블을 사용합니다

인터페이스에 표시된 레이블을 대소문자와 문장부호까지 그대로 옮깁니다. 버튼에 Add member라고 적혀 있으면 "Add a user"라고 쓰지 않습니다. 독자는 화면의 단어와 대조하며 읽습니다.

레이블은 굵게 표시해 문장에서 구분합니다. 레이블을 찾기 어렵거나 여러 곳에 나타날 때만 위치를 함께 씁니다. 예: "Select Export in the toolbar, not in the File menu."

두 곳에 나타나는 레이블

같은 레이블이 두 곳에 나타나는데 단계에서 레이블만 적으면 독자가 잘못된 곳을 누를 수 있습니다. 대화상자는 툴바 버튼과 같은 단어를 자주 반복합니다. "Select Export"만 적힌 단계는 두 컨트롤 중 어느 쪽으로도 읽힐 수 있습니다. 단계가 가리키는 위치를 적고, 독자가 다음에 보게 될 결과를 함께 적습니다. 예: "Select Export in the toolbar. The export dialog opens." 두 번째 문장은 독자가 계속하기 전에 올바른 컨트롤을 눌렀는지 확인하게 합니다.

메뉴에는 두 번째 문제가 있습니다. Settings 메뉴 항목이 앱 메뉴와 창 툴바에 모두 있을 수 있습니다. 독자에게 경로가 필요할 때만 경로를 쓰고, 메뉴를 처음 사용하는 단계에서 한 번만 씁니다.

독자의 검색을 위한 레이블 규칙

독자는 레이블을 찾지 못하면 화면에서 정확한 텍스트를 검색하는 경우가 많습니다. 바꿔 쓴 표현은 독자를 엉뚱한 곳으로 보내거나 아무 곳에도 보내지 못합니다. 아래 표는 이 규칙을 적용한 예입니다.

버전마다 바뀌는 레이블에는 메모가 필요합니다. 페이지 설명에 버전을 적습니다. 예: "In version 4, the button reads Invite." 메모가 있으면 독자가 묻기 전에 질문이 해결됩니다.

단계마다 결정 하나만 담습니다

단계에는 동작 하나 또는 선택 하나만 담습니다. "Open Settings, select Billing, and change the plan"은 단계 세 개입니다. 긴 문장에서는 독자가 화면으로 돌아왔을 때 위치를 잃습니다.

예외는 같은 작은 영역에서 항상 함께 일어나는 두 동작입니다. 예: "Enter the code and select Verify". 두 번째 동작에 조건이 붙으면 그때도 나눕니다.

결정 단계도 같은 주의가 필요합니다. 독자가 옵션 중에서 골라야 하면 단계에 옵션을 나열하거나, 선택을 좌우하는 설정의 이름을 적습니다. "Choose a format"은 옵션을 독자가 추측하게 합니다. "Choose PDF or PNG in Format. Choose PDF for print"는 독자가 두 번 읽지 않아도 적용할 수 있는 규칙을 줍니다.

복합 단계 나누기

복합 단계는 대개 결정 지점을 숨깁니다. 아래 예는 구독을 변경하는 단계 하나를 독자가 확인해야 하는 동작마다 나눕니다.

원래 문장에는 동사가 여섯 개, 확인이 하나 있었습니다. 위의 네 단계는 동작이 하나씩이고, 마지막 단계는 다음 절에서 다루는 체크포인트를 담습니다.

중요한 동작 뒤에 체크포인트를 둡니다

무언가를 바꾸는 동작 뒤에는 독자가 무엇을 보아야 하는지 적습니다. 예: "A green banner shows Changes saved." 체크포인트는 진행 상황을 확인하고, 독자가 다섯 단계 더 나아가기 전에 오류를 찾게 합니다.

저장, 제출, 가져오기, 권한 요청, 로딩에 시간이 걸리는 동작 뒤에 체크포인트를 둡니다.

오류 경로

체크포인트는 성공했을 때 보이는 상태를 알려 줍니다. 오류 경로는 실패했을 때 보이는 상태와 다음에 갈 곳을 알려 줍니다. 실패할 수 있는 체크포인트마다 경로를 하나씩 씁니다. 경로에는 화면에 보이는 메시지, 취할 동작, 되돌아갈 단계를 적습니다.

업로드 단계를 예로 듭니다. 성공 체크포인트는 "The file name appears in the list."입니다. 오류 경로는 다음과 같습니다. "If the list shows Upload failed, select Try again. If it fails a second time, go to the troubleshooting page for file size limits." 독자는 메시지를 확인하고, 취할 동작을 알고, 언제 멈춰야 하는지 압니다.

오류 경로는 짧게 유지합니다. 분기가 세 개인 경로는 별도 문제 해결 가이드로 옮기고 단계에서 링크합니다. 설명에 화면이 두 개 이상 필요한 경로는 대개 작업이 두 개입니다.

긴 가이드에서 체크포인트를 둘 위치

체크포인트가 없는 가이드는 독자가 여러 변경을 한 뒤에야 실패를 알게 되고, 그 변경을 되돌려야 합니다. 아래 수치는 단계 12개짜리 예제 가이드를 설명합니다. 체크포인트는 독자의 다음 동작이 결과에 달린 위치에 두었습니다.

"Done"처럼 상태만 말하는 체크포인트보다 화면에 보이는 결과를 말하는 체크포인트가 더 유용합니다. "Done"은 화면에서 아무것도 확인해 주지 않습니다. "The row shows Imported with 240 records"는 독자가 자신의 화면과 비교할 숫자를 줍니다.

화면에서 확인 가능한 조건으로 분기를 씁니다

분기에서 독자는 길을 잃기 쉽습니다. 독자가 알고 있어야 하는 내용이 아니라 화면에서 볼 수 있는 내용에 근거해 분기를 씁니다.

• 약함: "If you are on the legacy plan, ..."
• 명확함: "If the page shows Upgrade to continue, go to step 7."

분기는 짧게 유지합니다. 분기가 단계 두 개를 넘으면 별도 가이드로 옮기고 링크합니다.

독자의 이력에 의존하는 분기는 피합니다. "If you signed up before 2025"는 화면에 보이지 않는 사실을 기억하라고 요구합니다. 화면에 보이는 결과로 바꿉니다. 예: "If the account page shows a Legacy badge, go to step 7." 화면에 근거한 분기는 처음 보는 독자, 다시 찾아온 독자, 다른 사람을 위해 가이드를 확인하는 지원 담당자 모두에게 작동합니다.

화면에서 시작하는 분기

아래 흐름은 독자가 화면에서 확인할 수 있는 분기를 보여 줍니다. 독자는 자신이 어떤 요금제인지 알 필요가 없습니다.

분기는 독자를 알려진 지점으로 되돌립니다. 9단계는 내보내기를 할 수 없는 독자에게 가이드를 끝내므로, 나머지 독자는 그 부분을 건너뛸 필요가 없습니다.

스크린샷으로 위치와 상태를 보여 줍니다

텍스트는 무엇을 할지 말하고, 스크린샷은 어디에서 무엇이 보이는지 보여 줍니다. 단계마다 스크린샷 한 장을 쓰고, 관련 영역만 잘라 대상에 표시를 하나만 둡니다. 스크린샷은 상태도 보여 줍니다. 독자는 자신의 화면과 비교해 올바른 위치에 있는지 확인합니다.

Temposhot은 클릭을 기록해 이 쌍을 만듭니다. Action Capture를 열고(Command+3), Configure 아래에서 Parse clicked elements를 켠 뒤 Start Action Capture를 선택합니다. 인식된 클릭마다 클릭 직전 화면을 저장하고, Click "[[element-name]]" 같은 임시 제목을 붙입니다. Finish capture를 선택하면 편집기에서 Document가 열립니다.

각 스크린샷은 단계가 이름을 붙인 창이나 컨트롤까지 자릅니다. 전체 화면에는 컨트롤이 많아서 독자가 지시된 컨트롤을 직접 찾아야 합니다. 내보내기 전에 자른 영역에 계정 이름이나 관련 없는 알림 같은 개인 정보가 없는지 확인하고, 인쇄되거나 표시될 크기에서 이미지를 확인합니다.

임시 제목은 위 규칙에 따라 다시 씁니다. 예: Click "Save"를 "Select Save to keep the changes"로 바꿉니다. 체크포인트와 조건은 Page description에 적습니다. PDF 내보내기에서는 설명을 각 스크린샷 앞이나 뒤에 표시할 수 있습니다(Pro 전용 사용자 지정 기능). 편집기 가이드에서 제목, 설명, 도구를 다룹니다.

사용 방법 가이드용 설정

아래 설정은 보이는 대상이 있는 클릭마다 페이지 하나를 만듭니다. 단일 창에서 읽는 독자를 위해 쓴 가이드와 맞습니다.

클릭 없이 바뀌는 화면, 예를 들어 처리가 끝나야 상태가 바뀌는 화면에는 수동 단축키를 사용합니다. 이런 단계에서는 Show cursor in shortcut captures를 켜서, 독자가 읽어야 할 필드를 포인터가 가리키게 합니다.

가이드 전체에서 캡처 대상을 같게 유지합니다. 가이드 중간에 Active Window에서 Specific Window로 바꾸면 페이지의 구도가 일관되지 않습니다.

단계 페이지 작성용 편집기 키

대부분의 편집은 편집기에서 한 번에 한 페이지씩 이뤄집니다. 아래 키는 제목, 설명, 표시를 쓸 때 가장 많이 사용하는 동작을 다룹니다.

군더더기와 숨은 전제를 제거합니다

독자가 하는 일을 바꾸지 않는 단어는 삭제합니다.

• "Simply", "just", "easily": 아무 정보도 더하지 않으며, 어려움을 겪는 독자의 부담을 키웁니다.
• "You will now want to", "Go ahead and": 동사로 바로 시작합니다.
• "As mentioned above": 사실을 반복하거나 링크로 연결합니다.

그다음 전제를 찾습니다. 독자가 앱의 위치, 사용할 계정, 용어의 뜻을 알고 있는지 확인합니다. 빈틈마다 한 줄씩 추가하며, 보통 사전 준비 사항에 씁니다.

삭제량 측정

군더더기는 쉽게 추가되고 쉽게 놓칩니다. 편집 전후의 단어 수를 세면 한 번의 수정으로 얼마나 줄었는지 알 수 있습니다.

삭제는 페이지를 짧게 만드는 것 이상의 효과가 있습니다. 삭제된 구절마다 독자가 그것이 중요한지 판단하려고 멈추던 자리가 있었습니다. 수정된 단계는 처음 읽을 때부터 지시문으로 읽힙니다.

설명하지 않고 안내를 테스트합니다

작업을 해 본 적이 없는 사람에게 안내를 주고, 그 사람이 따라 하는 모습을 관찰합니다. 질문에는 답하지 않습니다. 멈춤이나 질문은 명확하게 고쳐야 할 동작, 레이블, 체크포인트를 가리킵니다.

테스터는 독자와 같은 사람으로 고릅니다. 제품을 만든 사람은 레이블과 흐름을 이미 알고 있으므로, 그 사람이 깔끔하게 끝내도 증명하는 것이 거의 없습니다. 지원팀 직원이나 대상 역할의 신규 직원은 작성자가 더 이상 보지 못하는 빈틈을 찾습니다. 테스터에게는 가이드와 사용할 계정만 주고, 그 밖에는 아무것도 주지 않습니다.

수정한 단계는 가능하면 다른 사람과 다시 테스트합니다. 깔끔하게 끝난 실행이 두 번 나오면 안내가 작동한다는 좋은 신호입니다. 스크린샷 튜토리얼 체크리스트에 게시 전 남은 확인 항목이 있습니다.

메모와 함께 세션 진행

멈춘 순간마다 시간과 단계 번호를 적고, 설명은 세션이 끝난 뒤로 미룹니다. 아래 타임라인은 단계 9개짜리 가이드의 세션과 유용한 발견 하나를 보여 줍니다.

메모는 어떤 단계에 레이블이 필요하고 어떤 단계에 체크포인트가 필요한지 보여 줍니다. 세션 하나는 비율이 아니라 패턴을 보여 주므로, 가이드를 다시 바꾸기 전에 두 번째 세션을 진행합니다.

how-to 가이드와 함께 보관하는 파일

가이드에는 페이지보다 많은 파일이 있습니다. 원본 Document는 Documents 라이브러리에 남고, 내보낸 PDF와 메모는 앱 밖의 한 폴더에 함께 둡니다. 이 폴더는 독자가 받는 파일 옆에 버전 번호와 테스트 메모를 보관하므로, 다음 수정이 같은 기록에서 시작됩니다.

자주 묻는 질문

안내에 "click"과 "select" 중 무엇을 써야 합니까?

"Select"는 마우스, 키보드, 터치에서 모두 작동합니다. 독자가 마우스를 쓰고 스타일 가이드가 "click"을 선호할 때만 "click"을 사용합니다. 무엇을 고르든 일관되게 씁니다.

단계 하나는 얼마나 길어야 합니까?

동작을 설명하는 문장 하나와, 필요하면 결과나 조건을 설명하는 문장 하나를 씁니다. 더 긴 설명은 메모나 별도 페이지에 씁니다.

안내에 번호가 매겨진 단계가 필요합니까?

순서가 중요하면 필요합니다. 번호는 독자가 자신의 위치를 기억하게 하고, 지원 담당자가 "step 4"처럼 지정해 말할 수 있게 합니다. Temposhot의 PDF 내보내기는 단계 번호를 추가할 수 있습니다(Pro).

경고는 어디에 둡니까?

경고가 적용되는 단계 앞에 둡니다. 파괴적인 동작 뒤에 두는 경고는 독자에게 너무 늦게 도착합니다.

가이드에는 스크린샷이 몇 장 필요합니까?

화면이 바뀌거나 대상을 찾기 어려운 단계마다 한 장입니다. 이미 보이는 필드에 텍스트만 입력하는 단계에는 필요하지 않습니다. 초안을 쓴 뒤 단계 수와 스크린샷 수를 비교하고, 같은 화면을 반복하는 스크린샷은 삭제합니다.

게시한 뒤 인터페이스가 바뀌면 어떻게 합니까?

바뀐 레이블이나 위치를 언급하는 단계를 모두 찾고, 스크린샷과 제목을 함께 갱신합니다. 옛 레이블이 적힌 새 스크린샷은 옛 스크린샷보다 독자를 더 혼란스럽게 합니다. 페이지 설명이나 가이드 바닥글에 앱 버전을 기록해, 독자가 어떤 버전을 설명하는지 구분할 수 있게 합니다.

키보드만 쓰는 독자를 위해 어떻게 씁니까?

단계가 특정 키나 포커스 대상에 의존하면 그 키나 대상을 이름으로 적습니다. 예: "Press Tab until the Export button has focus". 키보드 독자는 화면상의 위치를 같은 방식으로 볼 수 없으므로, "click"이나 컨트롤의 화면 위치에 의존하지 않습니다. 게시 전에 키보드만으로 한 번 테스트합니다.

체크포인트는 몇 개면 충분합니까?

저장, 제출, 가져오기, 권한 변경 동작마다 하나씩, 그리고 몇 초 이상 걸리는 단계마다 하나씩입니다. 체크포인트가 너무 많으면 독자의 진행이 느려지므로, 항상 함께 일어나는 두 동작의 체크포인트는 하나로 합칩니다.

클릭을 명확한 단계별 가이드로 바꿉니다

Action Capture는 클릭마다 스크린샷 한 장과 임시 제목 하나를 만들어, 이 작성 규칙을 바로 적용할 수 있게 합니다. Temposhot 다운로드에서 앱을 받고, 녹화를 바탕으로 다음 가이드를 작성합니다.