Style Guide
출처: 문서
본문
스타일 가이드
이 가이드는 OpenSearch 콘텐츠를 만들 때 적용하는 스타일 표준을 설명해요. 보충 정보가 필요하면 작성 가이드, 텍스트 포맷팅 가이드, 마크다운 포맷팅 가이드를 참고하세요.
우리 콘텐츠는 Microsoft Writing Style Guide, The Chicago Manual of Style, 그리고 Merriam-Webster를 따라요. 다만 이 가이드와 용어가 이런 참고 자료들보다 우선해요.
명명 규칙, 보이스와 톤, 브랜드 개성 특성
다음 섹션에서는 OpenSearch Project의 명명 규칙, 보이스와 톤, 브랜드 개성 특성에 대한 지침을 제공해요.
명명 규칙
OpenSearch Project 콘텐츠에서는 다음 명명 규칙을 따르세요:
- _OpenSearch Project_를 지칭할 때는 두 단어 모두 대문자로 표기해요.
- _OpenSearch_는 Amazon OpenSearch Service에서 사용되는 분산 검색 및 분석 엔진의 이름이에요.
- Amazon OpenSearch Service는 OpenSearch를 손쉽게 배포, 운영, 확장할 수 있게 해 주는 관리형 서비스예요. 처음 등장할 때는 전체 이름인 _Amazon OpenSearch Service_를 사용하세요. 이후 등장에서는 약칭인 _OpenSearch Service_를 사용할 수 있어요.
- Amazon OpenSearch Serverless는 Amazon OpenSearch Service의 온디맨드 서버리스 구성이에요. 처음 등장할 때는 전체 이름인 _Amazon OpenSearch Serverless_를 사용하세요. 이후 등장에서는 약칭인 _OpenSearch Serverless_를 사용할 수 있어요.
- OpenSearch Dashboards는 OpenSearch의 UI예요. 모든 등장에서 전체 이름인 _OpenSearch Dashboards_를 사용하세요.
- _Security Analytics_는 OpenSearch용 보안 정보 및 이벤트 관리(SIEM) 솔루션이에요. 솔루션 이름을 지칭할 때는 두 단어 모두 대문자로 표기해요.
- Observability는 Piped Processing Language(PPL)를 사용해 데이터 기반 이벤트를 시각화할 수 있게 해 주는 플러그인과 애플리케이션의 모음이에요. 솔루션 이름을 지칭할 때는 _Observability_를 대문자로 표기해요.
- OpenSearch Project의 고객은 _users_로, 더 넓은 사용자 집단은 _the community_로 지칭하세요. OpenSearch Project나 프로젝트에 참여하는 AWS 인력을 _team_이라고 부르지 마세요. 이는 커뮤니티 내부의 구분을 암시하기 때문이에요.
제품 이름
제품 이름은 대문자로 표기해요. OpenSearch Project에는 OpenSearch, OpenSearch Dashboards, OpenSearch Data Prepper라는 세 가지 제품이 있어요. 예를 들면 다음과 같아요:
- "_OpenSearch_를 설치하려면 Docker 이미지를 다운로드하세요."
- "_OpenSearch Dashboards_에 액세스하려면 브라우저를 열고 http://localhost:5601/app/home으로 이동하세요."
- "_OpenSearch Data Prepper_에는 다음과 같은 구성 요소가 포함되어 있어요:"
클라이언트와 도구의 이름도 대문자로 표기하세요. 예를 들면 다음과 같아요:
- "OpenSearch Python 클라이언트는 클러스터와 상호작용할 수 있는 더 자연스러운 문법을 제공해요."
- "Go 클라이언트는 기본적으로 요청을 최대 세 번까지 재시도해요."
- "_OpenSearch Kubernetes Operator_는 컨테이너화된 환경에서 OpenSearch와 OpenSearch Dashboards의 배포와 프로비저닝을 자동화하는 데 도움을 주는 오픈 소스 Kubernetes 오퍼레이터예요."
기능
기능은 사용자 경험을 이루는 개별 빌딩 블록으로, 제품의 기능성을 반영하며 여러 경험에서 공유돼요. 예를 들어, observability에 사용되는 SQL/PPL, reporting, notifications, alerting, anomaly detection은 일반 분석, 보안 분석, 검색 분석에 사용되는 것과 동일한 기능이에요. 탐색, 자격 증명 관리, 테마 설정 같은 사용자 경험의 구성 요소 역시 기능으로 간주돼요.
기능을 언급할 때는 OpenSearch 고유의 공식 명칭이 있는 기능이 아니라면 소문자로 표기하세요. 예를 들면 다음과 같아요:
- "_Remote-backed storage_는 실험적 기능이에요. 따라서 프로덕션 환경에서 _remote-backed storage_를 사용하는 것은 권장하지 않아요."
- "Snapshot API를 사용해 _snapshots_를 생성하고 복원할 수 있어요."
- "직관적인 드래그 앤 드롭 인터페이스를 통해 데이터 관계를 빠르게 탐색하려면 _VisBuilder_를 사용하세요." (VisBuilder를 단독으로 언급하거나 "visualization type"이라는 표현으로 용어를 한정할 수 있어요.)
플러그인
플러그인은 OpenSearch의 기능을 확장하는 독립적인 구성 요소예요. 기능을 설명할 때는 그 기능을 구현하는 플러그인을 언급하기보다 사용자 관점에서 서술하세요.
| 올바른 예 | 잘못된 예 |
|---|---|
| "OpenSearch는 머신 러닝(ML)에 대한 두 가지 별개의 접근 방식을 제공해요." | "ML Commons 플러그인은 머신 러닝(ML)에 대한 두 가지 별개의 접근 방식을 제공해요." |
| "AI 검색은 임베딩을 자동으로 생성하여 워크플로를 간소화해요." | "Neural Search 플러그인을 사용하면 임베딩을 자동으로 생성할 수 있어요." |
설정을 지칭할 때는 플러그인 이름보다 해당 설정이 제공하는 기능으로 부르는 것이 좋아요. 예를 들어 "Neural Search plugin settings"나 "k-NN plugin settings" 대신 "vector search settings"를 사용할 수 있어요. 이 설정들이 벡터 검색 기능을 지원하기 때문이에요. 플러그인 설정을 설명할 때는 필요한 경우에만 플러그인을 이름으로 언급하세요.
| 권장 | 허용 가능 |
|---|---|
| "쿼리 메트릭을 활성화하려면 다음 설정을 구성하세요:" | "쿼리 메트릭을 활성화하려면 다음 Query Insights 플러그인 설정을 구성하세요:" |
| "다음 설정을 수정하여 벡터 검색을 사용자 지정할 수 있어요." | "Neural Search 플러그인은 다음 설정을 지원해요." |
대부분의 플러그인은 표준 OpenSearch 배포판에 번들되어 있어요. 번들된 플러그인에 대한 설치 단계는 포함하지 마세요. 대신 해당 기능을 구성하거나 사용하는 방법을 바로 설명하세요. 기본적으로 번들되지 않는 플러그인(예: analysis-icu 플러그인)은 설치 단계가 필요해요.
플러그인을 이름으로 언급할 때는 항상 이름 뒤에 "plugin"이라는 단어를 붙이고, 플러그인 이름은 대문자로 표기하되 "plugin"이라는 단어는 대문자로 쓰지 마세요(예: "Query Insights plugin," "ML Commons plugin," "Notifications plugin"). 플러그인 이름을 고유명사처럼 단독으로 사용하지 마세요(예: "Anomaly Detection"이 아니라 "the Anomaly Detection plugin"을 사용하세요).
보이스와 톤
보이스는 작성자의 관점이나 문체예요. 보이스는 능동태나 수동태를 가리킬 수도 있지만, 동사의 시제(과거, 현재, 미래 등)를 가리킬 수도 있어요. 톤은 보이스에 깔린 정서적 바탕(차분함이나 분노 같은)이에요. 우리는 마치 한 명의 작성자가 모든 콘텐츠를 작성하는 것처럼 일관된 보이스와 톤으로 커뮤니티에 말하기 위해 노력해요. 공통의 보이스로 작성하는 것은 OpenSearch Project의 정체성과 브랜드를 확립하는 데에도 도움이 돼요.
보이스
OpenSearch Project의 보이스는 사람 중심이며, 사용자에게 직접 힘을 실어주는 데 초점을 맞춰요. 우리는 OpenSearch가 어떤 작업을 수행할 수 있는지보다 사용자가 OpenSearch로 무엇을 할 수 있는지를 강조하는 언어를 사용해요.
대부분의 경우 기능 관점에서 상황을 설명하기보다 사용자가 취하는 행동을 서술하도록 하세요. 예를 들어, 어떤 기능이 사용자가 무언가를 하도록 allows, enables, _lets_한다고 표현하는 대신 "You can do X by using this feature" 또는 "Use this feature to do X" 같은 표현을 사용하세요.
독자는 you(2인칭)로 지칭하고, OpenSearch Project는 we(1인칭)로 지칭하세요. 블로그 게시물의 작성자가 여러 명이라면 _we_를 사용해 작성자 개개인을 지칭할 수 있어요.
절차나 지침에서는 작성자("We also have to stop the container...")가 아니라 사용자("Then you can stop the container...")가 행동의 주체가 되도록 하세요. 1인칭 복수는 OpenSearch Project의 입장에서 권장 사항, 경고, 설명을 전달할 때만 사용하세요.
가능한 한 수동태 대신 능동태를 사용하세요. 수동
| 성격 특성 | 설명 | 가이드라인 |
|---|---|---|
| 명확하고 정확함 | OpenSearch Project는 우리 커뮤니티가 정확한 사고와 철저한 문서화를 요구하는 역할과 조직에서 일하고, 개발하고, 구축한다는 걸 이해해요. 우리는 정확한 언어를 사용하기 위해 노력해요. 생각이 해석의 여지를 남기지 않고 우리가 의미하는 바를 명확하게 말하고, 주장을 사실과 수치로 뒷받침하고, 필요한 곳에 믿을 만하고 최신인 (제3자) 참고 자료를 제공하는 거죠. 우리는 쉽게 이해할 수 있는 평이하고 직접적인 언어로 소통해요. 복잡한 개념은 간결하고 모호함 없이 소개해요. 개략적인 콘텐츠는 사용자가 원할 때 찾아볼 수 있는, 더 깊이 있거나 기술적인 콘텐츠로 연결되는 링크로 뒷받침돼요. |
- 명확하게 쓰고 단어를 신중하게 고르세요. 독자를 생각하고 독자가 여러분의 주장을 어떻게 해석할 수 있을지 생각해 보세요. - 구체적으로 쓰세요. 정확한 데이터를 제공할 수 있다면 어림짐작이나 일반적인 주장은 피하세요. - 주장은 데이터로 뒷받침하세요. 뭔가 "더 빠르다"거나 "더 정확하다"면 얼마나 그런지 말해 주세요. - 제3자 참고 자료를 인용할 때는 직접 링크를 포함하세요. |
| 투명하고 개방적임 | 오픈 소스 프로젝트로서 우리는 커뮤니티와 접근하기 쉽고 투명한 방식으로 정보를 주고받아요. 제품 계획은 GitHub에 공개적으로 게시하고, 포럼 및/또는 블로그를 통해 프로젝트와 관련된 시의적절한 정보를 공유하며, 제품과 기능 개발에 관한 열린 대화는 공개적인 장에서 이어가요. 누구나 우리 로드맵을 보고, 질문이나 이슈를 제기하고, 커뮤니티 미팅에 참여할 수 있어요. | - 완전한 이야기를 들려주세요. 해결 방법을 독자에게 안내하거나 소식을 전할 때는 중요한 정보를 건너뛰지 마세요. - 솔직하게 전하세요. 시의성 있는 뉴스와 정보는 빠짐없이 제때 전달하세요. - 독자가 알아야 할 내용이 있다면 앞부분에서 말하세요. 핵심을 뒤로 묻어 두지 마세요. |
| 협력적이고 지원적임 | 우리는 돕기 위해 존재하는 커뮤니티의 일원이에요. 커뮤니티를 위해 유용한 자원과 해결 방법을 잘 찾아내고자 노력하고, 다른 사람들도 그렇게 하도록 독려해요. 아이디어가 열린 마음으로 오갈 수 있도록, 커뮤니티가 서로 질문하고 답변할 수 있는 포럼을 제공해요. | - 독자를 환영하고 몰입시키는 대화체 언어를 사용하세요. 대화를 나누세요. - 토론과 피드백을 환영하세요. 의견 요청(requests for comment, RFCs), 커뮤니티 포럼, 커뮤니티 미팅 등 열린 토론을 위한 여러 메커니즘이 있어요. |
| 믿음직하고 친근함 | 우리는 사실과 데이터에 기반을 둬요. 제품이 할 수 있는 것을 과장하지 않아요. 겸손하면서도 권위 있는 방식으로 지식을 보여주고, 약속한 것은 믿을 수 있게 지켜요. 독자가 우리 제품을 직접 탐색해 볼 수 있게 메커니즘과 지원을 제공함으로써, 우리의 행동이 항상 말과 일치한다는 걸 보여줘요. 우리는 친근하고 환영하는, 편견 없는 방식으로 커뮤니티와 이야기해서 독자가 우리를 다가가기 쉬운 존재로 느끼게 해요. 우리 콘텐츠는 사람 중심이고, 사용자가 직접 힘을 가질 수 있도록 하는 데 초점을 맞춰요. |
- 주장과 단언은 사실과 데이터에 근거하고 그에 맞게 뒷받침하세요. - 과장하거나 부풀리지 마세요. 사실과 결과가 스스로 말하게 하세요. - 독자가 우리 제품을 직접 탐색하도록 권하세요. 그렇게 할 수 있도록 도움이 되는 안내를 제공하세요. - 직접적이고 대화체로 쓰세요. 독자와 대화하세요. 콘텐츠를 만들 대상에게 직접 말하는 것처럼 쓴다고 상상해 보세요. - 커뮤니티의 일원으로서, 커뮤니티를 위해 쓰세요. OpenSearch에 관한 콘텐츠를 만들거나 소비하는 사람은 누구나 더 나은 검색과 분석 솔루션을 배우고 만드는 데 공동의 관심을 가진 같은 그룹의 멤버예요. |
| 포용적이고 접근 가능함 | 오픈 소스 프로젝트로서 OpenSearch Project는 모두를 위한 것이고, 우리는 포용적이에요. OpenSearch 커뮤니티 안에서 다양한 배경과 관점을 소중히 여기고, 경험 수준과 상관없이 모든 기여자의 피드백을 환영해요. 장애가 있는 사람도 콘텐츠를 인지하고, 탐색하고, 상호작용할 수 있도록 콘텐츠를 설계하고 만들어요. 이를 통해 문서가 모두에게 이용 가능하고 유용하다는 게 보장되고, 콘텐츠의 전반적인 사용성 개선에도 도움이 돼요. 우리 커뮤니티가 국제적이라는 걸 이해하고, 글쓰기에도 그걸 반영해요. 더 넓은 커뮤니티에게 명확하지 않을 수 있는 관용구와 은유를 피한 평이한 언어를 사용해요. |
- 다양하고 글로벌한 OpenSearch Project 독자와 연결되도록 포용적인 언어를 사용하세요. - 단어 선택에 신중하세요. - 민감한 표현은 피하세요. - 공격적인 표현은 사용하지 마세요. - 장애인 차별적이거나 성차별적인 언어, 인종차별적 구조나 고정관념을 영속화하는 언어는 사용하지 마세요. - 링크: 대상 페이지를 충분히 설명하는 링크 텍스트를 사용하세요. 예를 들어 "여기"나 "이 링크" 대신 대상 페이지의 제목을 사용하세요. 대부분의 경우 정식 상호 참조(링크하는 페이지의 제목)가 맥락을 제공하고 독자가 링크를 선택했을 때 어디로 가는지 이해하는 데 도움이 되기 때문에 선호되는 스타일이에요. - 이미지: - 각 이미지에 충분한 맥락을 제공하는 소개 텍스트를 추가하세요. - 스크린 리더를 위해 이미지를 설명하는 ALT 텍스트를 추가하세요. - 절차: 모두가 마우스를 사용하는 건 아니에요. 그러니 기기에 종속되지 않는 동사를 사용하세요. 예를 들어 "클릭" 대신 "선택"을 사용하세요. - 위치: 콘텐츠에서 이미지나 다른 섹션 같은 다른 요소의 위치를 설명할 때는 "위"와 "아래" 대신 "앞의", "이전", "다음" 같은 단어를 사용하세요. |
포용적인 콘텐츠
OpenSearch Project 문서를 개발할 때 저희는 포용적이고 편견 없는 콘텐츠를 만들기 위해 노력해요. 저희는 다양한 글로벌 OpenSearch Project 독자와 소통하기 위해 포용적인 언어를 사용하고, 단어 선택에도 신중을 기해요. 포용적이고 편견 없는 콘텐츠는 모든 독자에게 콘텐츠의 명확성과 접근성을 높여 주기 때문에, 저희는 장애인을 차별하는 표현이나 성차별적 표현, 인종차별적 구조나 고정관념을 지속시키는 표현은 피해요. 실제로 이는 특정 용어가 콘텐츠에 등장하는 것을 허용하지 않고, 맥락에 따라서는 다른 용어의 사용도 피한다는 뜻이에요.
저희의 철학은, 일부 맥락에서 문제가 될 수 있는 용어의 사용을 적극적으로 줄여 나가면서 사용자와 업계에 긍정적인 영향을 미친다는 것이에요. 대신 기술적으로 더 정확한 언어와 모든 독자를 포용하는 용어를 사용해요.
공격적인 용어
다음 공격적인 용어는 가능한 한 OpenSearch Project 콘텐츠에 등장하지 않아야 해요. 이 용어들 중 상당수는 아직 기존 코드에 남아 있지만 교체 작업이 진행되고 있다는 점에 유의하세요. 예를 들어 slave는 2018년에 Python 프로그래밍 언어에서 제거되었고, 오픈소스 커뮤니티는 이러한 용어를 교체하기 위한 작업을 계속하고 있어요.
| 사용하지 마세요 | 대신 사용하세요 |
|---|---|
| blacklist | deny list |
| master | primary, main, leader |
| master node | cluster manager node |
| slave | replica, secondary, standby |
| whitelist | allow list |
민감한 용어
다음 용어들은 일부 맥락에서 문제가 될 수 있어요. 이 용어들을 사용할 수 없다는 뜻은 아니에요. 다만 사용할 때 잠재적인 연상 의미를 유의하고, 사람을 지칭할 때는 사용하지 않도록 하세요.
| 사용을 피하세요 | 대신 사용하세요 |
|---|---|
| abort | stop, end, cancel |
| blackout | service outage, blocked |
| kill | stop, end, clear, remove, cancel 예외: UNIX kill 명령어를 언급할 때는 kill을 사용하세요. |
상표 정책
"OpenSearch" 워드마크는 정확한 형태 그대로 사용해야 하며, 축약하거나 다른 단어와 결합해서는 안 돼요(예를 들어 "OPNSRCH"나 "OpenSearch-ified"가 아니라 "OpenSearch" 소프트웨어). 자세한 내용은 OpenSearch 상표 정책을 참조하세요. OpenSearch 로고 사용에 관한 지침은 이 정책과 OpenSearch 브랜드 가이드라인을 참고하세요. 다른 회사의 로고를 사용할 때는 해당 회사의 상표 가이드라인을 참고하세요.