jakubkrehel/better-writing

인터페이스 작성

명확하고 간결함이 재치보다 낫습니다. 일관성이 다양성보다 낫습니다. 가장 좋은 오류 메시지는 오류가 발생하지 않도록 상호작용을 재설계하는 것입니다.

카피의 렌더링 방식(text-transform을 통한 대문자화, 생략 부호, 스마트 구두점)은 better-typography에 속합니다. 오류 마크업 및 알림(aria-invalid, 라이브 리전)은 better-accessibility에 속합니다. 번역 문자열을 위한 공간은 better-layout에 속합니다.

기존 목소리 파악

작성하거나 검토하기 전에 주변 카피를 읽어보세요. 제품의 용어, 지역화 규칙, 음성 또는 콘텐츠 스타일 가이드를 확인하세요.

의도적인 브랜드 음성은 결함이 아닙니다. 평이한 언어에서 벗어난 부분이 불일치, 모호함, 번역 위험 또는 상황이 뒷받침하지 않는 어조를 만들 때만 지적하세요.

하나의 목소리, 유연한 어조

제품은 하나의 목소리를 가지며, 기존 카피가 이를 확립합니다. 로컬 편집이 새로운 목소리를 만들어내서는 안 됩니다. 용어를 일관되게 유지하세요: 메뉴에서 "보관"이라면, 토스트에서는 "저장소로 이동"이 아닙니다. 어조는 상황에 따라 유연하게 변합니다:

맥락	어조
성공, 온보딩, 빈 상태	따뜻함, 가벼울 수 있음
일상적인 작업, 설정	중립적, 최소한
오류, 파괴적 확인	차분함, 평이함, 장난기 없음
데이터 손실, 보안	진지함, 명시적

독자에게 직접 말하기

안내 카피에서는 "사용자"가 아닌 "당신"이라고 쓰세요. 오류에서는 "저희"가 모호함을 불러일으키고 회피처럼 읽히므로, "이 콘텐츠를 불러오는 데 문제가 있습니다"보다 "콘텐츠를 불러올 수 없습니다"를 선호하세요. 확립된 1인칭 음성은 여전히 명확하게 읽히는 위험이 낮은 카피에서 유지될 수 있습니다.

소유격은 드물게 사용하세요: "당신의 즐겨찾기"보다 "즐겨찾기"가 낫습니다. 흐름 전체에서 하나의 관점을 유지하세요.

재치보다 평이한 단어

지친 독자가 한 번에 이해할 수 있는 단어를 선택하고, 아무 역할도 하지 않는 단어는 모두 삭제하세요. 관용구, 구어체, 번역되지 않을 유머는 사용하지 마세요.

불필요한 성별 구분은 피하세요: "각 가입자는 자신의 레시피를 게시할 수 있습니다"가 아니라 "가입자는 레시피를 게시할 수 있습니다." 입력 장치에 맞추세요: 터치에서는 "탭", 포인터에서는 "클릭", 둘 다 가능할 때는 "선택"을 사용하세요.

변수 주위를 조각으로 문장을 조립하지 마십시오("You have " + n + " new messages"). 언어마다 단어 순서가 다르기 때문입니다. 적절한 복수형이 포함된 완전한 템플릿 문자열을 사용하세요.

동사 우선 버튼

버튼 레이블은 동사로 시작하여 동작을 명명합니다: "보내기", "초안 저장", "프로젝트 삭제". "확인!", "시작해볼까요!" 또는 중요한 동작에 단순히 "예"와 "아니요"를 사용하지 마세요.

확인 버튼은 결과를 반복하여 본문을 읽지 않고도 대화상자에 응답할 수 있게 합니다. "이 프로젝트를 삭제하시겠습니까?"는 프로젝트 삭제와 취소를 제공합니다.

일관된 흐름 용어

여러 단계로 구성된 흐름은 전체에 걸쳐 하나의 용어를 사용합니다: 시작하려면 "시작하기", 진행하려면 "계속" 또는 "다음"(하나 선택), 완료하려면 "완료". 동의어를 번갈아 사용하면 사용자가 버튼이 다른 작업을 수행하는지 의문을 갖게 됩니다.

링크는 목적지를 설명

링크 텍스트는 문맥 밖에서도 의미가 있어야 합니다. 스크린 리더 사용자는 페이지 링크 목록으로 탐색하기 때문입니다. "청구 문서 읽기"라고 쓰세요. "여기를 클릭"은 이 규칙과 장치 동사 규칙을 동시에 위반합니다.

단순한 "더 알아보기"는 페이지에 두 개 이상 나타나면 바로 의미가 무너집니다. 각각에 접미사를 붙이세요: "내보내기에 대해 더 알아보기".

하나의 대문자화 정책

요소 유형별로 제목 스타일이나 문장 스타일을 선택한 다음, 해당 유형의 모든 인스턴스에 적용하세요. 문장 스타일이 더 안전한 기본값입니다. 더 차분하고, 기억해야 할 단어별 규칙이 없으며, 지역화가 깔끔합니다. "변경사항 저장" 옆에 "변경사항 취소"가 있으면 부주의해 보입니다.

설정은 켜짐 상태를 설명

토글의 레이블은 켜져 있을 때 어떤 일이 일어나는지 설명하세요. "읽음 확인 보내기"는 사용자가 꺼짐 상태를 추론할 수 있게 하지만, 부정형("읽음 확인 보내지 않기")은 토글을 이중 부정으로 만듭니다.

설정으로 가는 경로를 설명하지 말고 참조하는 설정으로 직접 연결하세요: "설정 > 알림 > 이메일"로 가는 경로가 아닌 "알림 설정" 링크.

오류는 고치는 방법을, 발생한 곳 옆에 알려줌

오류는 지침이며, 실패한 필드 옆에 있어야 합니다:

나쁨	좋음
해당 비밀번호가 너무 짧습니다	8자 이상의 비밀번호를 선택하세요
잘못된 이름	이름에는 문자만 사용하세요
이런! 문제가 발생했습니다.	저장할 수 없습니다. 연결을 확인하고 다시 시도하세요.

비난, "이런", 느낌표는 사용하지 마세요. 힌트는 긍정적으로 표현하고("숫자나 기호를 사용하지 마세요"가 아닌 "문자만 사용하세요"), 실수 후가 아니라 실수 전에 보여주세요. 동일한 오류가 계속 발생하면, 문구를 바꾸는 대신 상호작용을 재설계하세요.

빈 상태는 앞을 가리킴

빈 상태는 이곳이 무엇인지, 어떻게 채울 수 있는지, 그리고 하나의 명확한 다음 동작을 제시해야 합니다:

<!-- 나쁨: 어깨를 으쓱 -->
<p>결과 없음.</p>

<!-- 좋음: 방향 제시와 다음 단계 -->
<p class="font-medium">아직 프로젝트가 없습니다</p>
<p class="text-sm text-zinc-500">프로젝트는 작업과 파일을 함께 유지합니다.</p>
<button class="mt-4">프로젝트 만들기</button>

검색 또는 필터 빈 상태는 쿼리를 명명하고 종료 옵션을 제공합니다: "'분기별'에 대한 결과 없음. 필터 지우기". 빈 상태에 영구적인 정보를 절대 배치하지 마세요. 콘텐츠가 존재하는 순간 사라집니다.

플레이스홀더는 예시이지 레이블이 아님

플레이스홀더는 예상 형식을 보여줍니다: [email protected], DD/MM/YYYY. 입력 시 사라지므로 유일한 레이블이 되어서는 안 됩니다. 모든 필드는 보이는 레이블을 유지해야 합니다.

보고

심각도. HIGH는 사용자를 오도하거나 오류로부터 복구하는 방법을 숨깁니다. MEDIUM은 음성, 용어 또는 대문자화 일관성을 위반합니다. LOW는 고립된 단어 다듬기입니다.

검증. 여기서는 소스만으로 충분합니다. 모든 레이블이 호출하는 동작과 일치하는지, 모든 오류에 대해 명시된 수정 방법이 있는지, 용어가 주변 카피와 일관되는지 확인하세요. 브라우저 확인은 필요하지 않습니다.

형식. 발견 사항을 위반하는 원칙 아래에 그룹화하고, 심각도 순서대로 정렬하며, 각 근본 원인에 대해 나타나는 모든 위치를 나열하는 한 행을 만듭니다:

심각도	위치	변경 전	변경 후	이유

위치는 path/to/file:line입니다. 이유는 원칙과 사용자 영향을 명명합니다.

HIGH가 남아 있으면 Block으로, 그렇지 않으면 Approve로 끝내고, 나머지는 작업할 내용으로 테이블에 남겨둡니다. 검사하지 않은 범위에 대해 Approve하지 마십시오. 보고할 내용이 없으면 "실행 가능한 작성 관련 발견 사항 없음"을 명시하고 검증을 보고하세요.