문서 스타일 가이드

이 스타일 가이드에서는 Elastic의 친근한 어조와 편집 품질에 대한 우리의 지향을 반영하는, 명확하고 일관된 문서를 작성하기 위한 편집 지침을 확인할 수 있습니다.

이 빠른 참조는 스타일 가이드의 요약입니다. 더 자세한 내용은 각 섹션을 참고하세요.

일관된 목소리는 신뢰를 쌓고 우리 문서가 하나의 팀에서 나온 것처럼 느껴지게 합니다. 어조는 맥락에 따라 달라지지만—튜토리얼에서는 친근하게, 문제 해결에서는 직설적으로—목소리는 분명하게 Elastic답게 유지됩니다.

• 인간적이고, 공감하며, 사용자 중심으로 쓰세요.
• 능동태와 현재 시제를 사용하세요.
• 내용에 보탬이 되지 않는 단어는 빼세요.
• 지시문에서 "please"는 피하세요.

전체 지침은 목소리와 어조를 참고하세요.

접근성 있는 콘텐츠는 사용자가 어떤 방식으로 문서를 이용하든 모두가 내용을 이해할 수 있게 합니다. 포용적인 언어는 우리 글로벌 커뮤니티의 다양성을 존중하고 반영합니다.

• 모든 이미지와 미디어에 대체 텍스트를 추가하세요.
• 의미 있는 링크 텍스트를 사용하세요("여기를 클릭"은 피하세요).
• 방향을 나타내는 표현(위, 아래, 왼쪽, 오른쪽)은 피하세요.
• 기기에 구애받지 않는 표현을 사용하세요(click이 아니라 select).
• 성별 중립 대명사(they/their)를 사용하세요.

전체 지침은 접근성과 포용성을 참고하세요.

올바른 문법과 일관된 철자는 모호함을 줄이고, 독자가 오류에 걸려 넘어지는 대신 내용에 집중하도록 돕습니다. 이러한 관례는 현지화와 번역 작업에도 도움이 됩니다.

• 2인칭 대명사(you, your)를 사용하세요.
• 옥스퍼드 콤마를 사용하세요.
• 미국식 영어 철자를 사용하세요.
• 약어는 처음 쓸 때 풀어서 쓰세요.
• 문장식 대문자 표기를 사용하세요.

전체 지침은 문법과 철자를 참고하세요.

일관된 서식은 사용자가 콘텐츠를 빠르게 훑어보고 개념 간의 관계를 파악하는 데 도움이 됩니다. 굵게, 기울임, 고정폭 같은 시각적 단서는 UI 요소, 용어, 코드를 한눈에 구분해 줍니다.

• UI 요소는 굵게, 새로운 용어는 기울임, 코드는 고정폭으로 표기합니다.
• 1–9는 글자로 쓰고, 10 이상은 숫자로 씁니다.
• 목록은 병렬 구조로 2개 이상의 항목이 필요합니다.
• 문단은 7줄 이내로 유지하세요.

전체 지침은 서식을 참고하세요.

명확한 UI 문서는 사용자가 작업을 효율적으로 완수하도록 돕습니다. 사용자가 다루는 모든 요소를 설명하기보다, 사용자가 무엇을 해야 하는지에 집중하세요.

• UI를 하나하나 설명하지 말고 사용 사례에 집중하세요.
• 절차는 5–9단계로 유지하세요.
• 탐색 경로에는 화살표를 사용하세요: 메뉴 → 하위 메뉴 → 항목.
• 접근성을 위해 아이콘 툴팁을 포함하세요.

전체 지침은 UI에 관해 쓰기를 참고하세요.

적절한 단어는 문서를 더 명확하고, 더 포용적이며, 현지화하기 쉽게 만듭니다. 일관된 용어는 혼란을 줄이고 사용자가 필요한 것을 찾도록 돕습니다.

• 권장: select, enter, edit, view, create, delete, add, remove.
• 지양: abort, blacklist/whitelist, click, easy, please, simple.

전체 지침은 단어 선택을 참고하세요.

Vale linter는 문서를 작성하는 동안 스타일 문제를 점검하는 데 도움이 됩니다. Vale은 흔한 스타일 가이드 위반을 자동으로 표시해 주므로, 게시 전에 문제를 발견하고 수정할 수 있습니다.