Home » » 5장. 스크린샷, FAQ, 오류 대응으로 막힘 없이 안내하기

5장. 스크린샷, FAQ, 오류 대응으로 막힘 없이 안내하기

By 

5장. 스크린샷, FAQ, 오류 대응으로 막힘 없이 안내하기

1~4장에서 블로그 글 구조와 GitHub 연동 방법을 만들었다면, 5장에서는 독자가 실제로 따라 하는 과정에서 막히지 않도록 돕는 스크린샷, FAQ, 오류 대응 섹션을 설계합니다. 이 장을 잘 만들어 두면 댓글·문의 대응 시간이 크게 줄고, 전자책 신뢰도도 함께 올라갑니다.

5-1. 스크린샷으로 설치 과정을 시각화하기

텍스트만으로 설치 과정을 설명하면, 특히 초보자는 중간에 쉽게 길을 잃습니다. 각 단계마다 핵심 화면을 캡처해 “여기까지 왔다면 맞게 따라오고 있는 것”을 눈으로 확인하게 해 주는 것이 중요합니다.

1) 어떤 화면을 반드시 캡처해야 할까?

  • GitHub 리포지토리 메인 화면 (Code 버튼, Download ZIP 위치)
  • Upload files 화면 (파일 드래그 구역, Commit changes 버튼)
  • 코드 에디터에서 index.html이 열린 화면
  • 블로그 에디터 HTML 모드에 코드가 붙어 있는 화면
  • 최종적으로 블로그 화면에 버튼·위젯이 노출된 장면

전자책에서는 각 스크린샷에 번호를 붙이고, 본문에서 그 번호를 참조하는 방식이 좋습니다. 이렇게 하면 “그림 5-1을 참고하세요”라는 식으로 안내할 수 있습니다.

2) 스크린샷 캡션과 설명 HTML 예시

아래는 전자책/블로그에서 그대로 사용할 수 있는 스크린샷 삽입 예시입니다.

<figure>
  <img src="images/5-1-github-download-zip.png"
       alt="GitHub 리포지토리에서 Download ZIP 버튼 위치">
  <figcaption>
    그림 5-1. GitHub 리포지토리에서 <strong>Download ZIP</strong> 버튼 위치
  </figcaption>
</figure>

이처럼 <figure>와 <figcaption> 태그를 사용하면, 전자책에서도 이미지와 설명을 하나의 덩어리로 관리하기가 쉽습니다.

3) 단계별 스크린샷을 묶어 보여주는 예시

<h2>설치 과정 한눈에 보기</h2>

<ol>
  <li>GitHub에서 예제 리포지토리로 이동합니다. (그림 5-1 참고)</li>
  <li>Code 버튼을 클릭하고 Download ZIP을 선택합니다. (그림 5-2 참고)</li>
  <li>압축을 풀고 index.html을 코드 에디터로 엽니다. (그림 5-3 참고)</li>
  <li>코드를 블로그 HTML 모드에 붙여넣습니다. (그림 5-4 참고)</li>
</ol>
  
<figure>
  <img src="images/5-1-step1-repo.png" alt="예제 리포지토리 메인 화면">
  <figcaption>그림 5-1. 예제 리포지토리 메인 화면</figcaption>
</figure>

<figure>
  <img src="images/5-1-step2-download.png" alt="Download ZIP 버튼 위치">
  <figcaption>그림 5-2. Download ZIP 버튼 위치</figcaption>
</figure>

5-2. 자주 묻는 질문(FAQ) 섹션 설계

FAQ 섹션은 독자가 실제로 겪는 반복 질문을 한 번에 정리해 두는 공간입니다. “질문–답변” 구조를 명확하게 유지하면, 독자도 필요한 정보를 빠르게 찾을 수 있습니다.

1) FAQ 작성 원칙

  • 질문은 독자가 실제로 쓸 법한 문장으로 쓴다. (예: “버튼을 눌렀는데 다운로드가 안 돼요”)
  • 답변은 짧은 요약 → 필요한 경우 단계별 가이드 순서로 쓴다.
  • 가능하면 스크린샷이나 코드 예시 링크를 함께 제공한다.

2) FAQ HTML 구조 예시

<h2>자주 묻는 질문(FAQ)</h2>

<h3>Q1. 다운로드 버튼을 눌렀는데 아무 변화가 없습니다.</h3>
<p>
A1. 대부분의 경우, href 주소가 잘못되었거나 GitHub 리포지토리가 비공개로 설정된 상태입니다.
아래 두 가지를 순서대로 확인해 주세요.
</p>
<ol>
  <li>버튼 코드의 href가 ZIP 다운로드 주소인지 확인합니다.</li>
  <li>GitHub 리포지토리가 Public 상태인지 확인합니다.</li>
</ol>

<h3>Q2. 모바일에서 버튼이 잘려 보입니다.</h3>
<p>
A2. 버튼에 고정 너비가 설정되어 있으면 작은 화면에서 잘릴 수 있습니다.
width 속성을 제거하거나, 100% 너비로 설정해 보세요.
</p>

<h3>Q3. 코드 그대로 붙였는데 블로그 편집기에서 오류가 납니다.</h3>
<p>
A3. 일부 블로그 편집기는 &lt;style&gt; 태그를 제한하기도 합니다.
이 경우, CSS는 별도 설정 메뉴에 넣고 본문에는 HTML만 붙여넣어 주세요.
</p>

이런 형태의 FAQ는 전용 페이지로 빼서 모아 두거나, 각 다운로드 포스트 하단에 공통으로 붙여둘 수 있습니다.

3) 전자책용 FAQ 블록

전자책에서는 FAQ를 별도 박스로 강조하면 가독성이 좋아집니다.

<section class="faq-block">
  <h2>FAQ – 설치 중 자주 묻는 질문</h2>

  <h3>Q. GitHub 링크를 눌렀는데 404 오류가 납니다.</h3>
  <p>
  A. 리포지토리 이름이나 브랜치 이름이 바뀐 경우입니다.
  전자책에 적힌 주소 대신, 실제 GitHub에서 주소를 다시 복사해 붙여넣으세요.
  </p>
</section>

5-3. 오류 대응(트러블슈팅) 섹션 만들기

오류 대응 섹션은 단순 질문을 넘어, “문제가 발생했을 때 스스로 해결할 수 있게 돕는 작은 매뉴얼”입니다. 좋은 오류 가이드는 문제 상황을 명확히 묘사하고, 원인과 해결 단계를 순서대로 제시합니다.

1) 좋은 오류 메시지와 가이드의 구성

  • 상황 요약: “무슨 일을 하다가 어떤 메시지가 떴는지”
  • 가능한 원인: 1~2개의 대표 원인 정리
  • 해결 단계: 따라 할 수 있는 순서형 가이드
  • 추가 도움: 그래도 해결되지 않을 때 확인할 것

2) 트러블슈팅 HTML 예시 1 – 다운로드가 안 될 때

<h2>오류 해결 가이드</h2>

<h3>문제 1. 다운로드 버튼을 눌러도 파일이 내려받아지지 않을 때</h3>
<p>
다음과 같은 상황일 수 있습니다.
</p>
<ul>
  <li>버튼은 보이지만, 클릭해도 아무 반응이 없다.</li>
  <li>새 탭이 열리지만 “404 Not Found” 페이지가 나온다.</li>
</ul>

<h4>가능한 원인</h4>
<ul>
  <li>href 속성에 입력한 주소가 잘못되었거나 오타가 있다.</li>
  <li>GitHub 리포지토리가 Private(비공개) 상태이다.</li>
</ul>

<h4>해결 방법</h4>
<ol>
  <li>GitHub 리포지토리에서 Code 버튼을 클릭하고 Download ZIP 메뉴를 다시 확인합니다.</li>
  <li>브라우저 주소창에서 ZIP 주소를 복사한 뒤, 버튼 href에 그대로 붙여넣습니다.</li>
  <li>리포지토리 Settings에서 Public 상태인지 확인합니다.</li>
</ol>

3) 트러블슈팅 HTML 예시 2 – 블로그 편집기 오류

<h3>문제 2. 블로그 편집기에서 “허용되지 않는 태그” 오류가 날 때</h3>
<p>
일부 블로그 플랫폼은 &lt;script&gt;나 &lt;style&gt; 같은 태그를
본문에서 제한하기도 합니다.
</p>

<h4>가능한 원인</h4>
<ul>
  <li>HTML 모드가 아닌 일반 편집 모드에 코드를 붙여넣은 경우</li>
  <li>플랫폼 정책상 허용되지 않는 태그를 사용한 경우</li>
</ul>

<h4>해결 방법</h4>
<ol>
  <li>편집기의 HTML 또는 소스 모드로 전환했는지 확인합니다.</li>
  <li>본문에서는 &lt;div&gt;, &lt;a&gt;, &lt;ul&gt; 등 기본 태그만 사용합니다.</li>
  <li>CSS는 블로그 꾸미기/고급 설정/스타일 편집 메뉴에 별도로 추가합니다.</li>
</ol>

4) 트러블슈팅 섹션에 스크린샷 추가하기

오류 메시지가 뜨는 화면을 그대로 캡처해서 보여주면, 독자가 “내가 보는 화면과 같구나”라고 느끼면서 안심할 수 있습니다. 

<figure>
  <img src="images/5-3-editor-error.png"
       alt="블로그 편집기에서 허용되지 않는 태그 오류 메시지">
  <figcaption>
    그림 5-5. 블로그 편집기에서 허용되지 않는 태그 오류 메시지 예시
  </figcaption>
</figure>

5장 정리

5장에서는 스크린샷, FAQ, 오류 대응 섹션을 이용해 독자가 설치·사용 과정에서 막히지 않도록 돕는 방법을 살펴봤습니다. 다음 장부터는 이런 실전 지원 요소들을 시리즈 구조, 수익화, 전자책 확장 전략과 어떻게 연결할지 이어서 다룰 수 있습니다.

5장. 스크린샷, FAQ, 오류 대응으로 막힘 없이 안내하기

#가나 투데이 #ganatoday

그린아프로
Share:  Facebook Twitter Google+