예쁜 미리보기와 편집할 원본은 다른 파일입니다

자료 소개 화면에는 표가 잘 보이는데, 받은 묶음에는 그림 파일만 있을 수 있습니다. 반대로 원본 표는 있지만 어떤 파일부터 열어야 하는지 설명이 없으면 사용자는 예제와 자신의 입력을 구분하기 어렵습니다. 디지털 자료는 파일 수보다 각 파일이 맡는 일을 먼저 보여주는 편이 정확합니다.

이 글의 예제 묶음에는 편집용 CSV, 브라우저에서 읽는 미리보기 HTML, 읽는 순서를 적은 안내, 버전 정보가 들어 있습니다. 실제 판매 제품을 평가하는 사례가 아니라 detailry에서 만든 작은 파일 묶음입니다. ZIP 안의 sample-files 폴더에서 같은 파일을 확인할 수 있습니다.

이름·형식·역할을 같은 행에 적습니다

예제 자료 묶음의 파일 목록
파일역할열었을 때 할 일
layout-source.csv편집할 항목의 원본section_id·title·kind 열을 확인하고 값을 입력
preview.html내용이 배치되는 모양 확인원본의 어느 항목을 보여주는지 읽음
readme.txt사용 순서와 파일 관계먼저 열고 원본·미리보기의 차이 확인
version.txt같은 묶음인지 식별묶음 이름과 버전 대조

미리보기가 편집기를 제공하지 않는다면 “브라우저에서 바로 편집”이라고 쓰지 않습니다. 그림이나 HTML에 값이 보인다는 사실과 그 값이 원본과 자동으로 동기화된다는 사실도 다릅니다. 이 예제의 미리보기는 정적인 문서이며 CSV를 고쳐도 자동 갱신하지 않습니다.

첫 화면에 열 순서와 필요한 동작을 남깁니다

sample-files/
  readme.txt        먼저 읽기
  layout-source.csv 편집 원본
  preview.html     표시 모양 확인
  version.txt      묶음 버전

파일 이름만으로 순서를 알기 어렵다면 안내에서 “1. readme 읽기 → 2. 원본 열기 → 3. 미리보기와 항목 관계 확인”처럼 연결합니다. 특정 앱의 독점 기능이 필요한 자료라면 실제 형식과 지원 조건을 별도로 알려야 합니다. 범용 텍스트라는 이름만으로 모든 프로그램에서 같은 표시를 보장하지는 않습니다.

파일을 배포하기 전에는 안내에 적은 파일이 실제로 들어 있는지 확인합니다. 예전 묶음의 readme만 복사하면 없는 폴더나 다른 버전의 이름을 가리킬 수 있습니다. 새 버전에서 파일을 추가하거나 지웠을 때 목록과 안내를 함께 바꿔야 합니다.

CSV는 표 모양보다 열의 관계를 확인합니다

예제의 CSV는 쉼표로 필드를 나누고 첫 줄에 열 이름을 둡니다. 값 자체에 쉼표가 들어가면 그 값을 따옴표로 감싸는 방식이 필요합니다. RFC 4180은 헤더, 필드 수와 따옴표 처리의 공통 형식을 설명합니다. 확장자만 CSV로 붙이는 것으로 구조가 만들어지지는 않습니다.

section_id,title,kind
hero,"규격, 구성",summary
details,치수표,table

첫 행의 “규격, 구성”은 한 셀입니다. 파일을 열었을 때 네 열로 갈라진다면 구분자나 인코딩을 확인해야 합니다. 예제에서는 UTF-8과 쉼표를 사용합니다. 자동으로 형식을 추측하는 앱도 있으므로 파일 형식과 열 수를 함께 적어 두면 결과를 대조하기 쉽습니다.

예제를 직접 열어 보기

이 글의 화면 예제와 소스 받기 ZIP. 압축을 푼 뒤 index.html을 브라우저에서 열 수 있습니다. 예제의 입력과 표시 범위는 각 화면의 안내를 기준으로 확인하세요.

참고한 원문