용어 사전 항목 작성하기
용어 사전 항목은 필수 요소 두 가지와 선택 요소 두 가지로 구성됩니다.
출처: 문서
본문
용어 사전 항목은 필수 요소 두 가지와 선택 요소 두 가지로 구성됩니다.
- 헤더(header)와
- 그 사물이 무엇인지 정의하는 문장 하나, 그리고
- 그 사물이 무엇인지에 대한 더 많은 맥락을 주고 정보를 더 얻을 수 있는 곳을 가리켜 주는 선택적인 문장 한두 개와
- 추가 정보로 연결되는 링크(선택 사항)입니다.
헤더 (The header)
헤더(와 첫 문장)는 사용자가 항목을 발견하는 경로입니다. 헤더는 두 부분으로 구성됩니다.
- 실제 용어(term): 가능한 한 최소화해야 합니다. 더 많은 정보는 항목 본문에 넣을 수 있습니다.
- 구분자(disambiguator): 특정 항목이 맥락에 따라 특정한 의미를 지니거나 다른 의미를 가질 때 사용자가 이해할 수 있게 해줍니다.
용어 (The term)
사전이라고 생각하면 됩니다. 단어 하나가 기본 단위이며 대부분의 정의는 단일 단어를 가리킵니다. 약어도 허용됩니다. 형용사와 명사의 조합도 유용합니다. 예를 들어 conditional decision, backstage framework 등이 있습니다. 3개에서 4개 단어를 넘어가면 단순화하려고 노력하고 더 많은 내용을 항목에 넣어야 합니다.
제목에서 용어는 Title Case(각 단어의 첫 글자를 대문자로)로 작성해야 합니다. 또한 단수여야 합니다.
구분자 (The disambiguator)
구분자의 목적은 맥락에 따라 특정한 의미를 가질 수 있는 용어를 구분하는 것입니다. 여기에는 두 가지 해석이 있습니다.
- 서로 다른 맥락 사이에 명확한 경계를 만들어야 하는 여러 용어가 있거나,
- 단일 맥락에 특정한 의미를 지닌 단일 용어가 있는 경우입니다.
첫 번째의 좋은 예는 resources입니다. 카탈로그 플러그인과 권한 플러그인 모두 resources라는 개념을 갖고 있지만, 같은 것을 가리키는 것은 아닙니다.
두 번째의 좋은 예는 Query translators입니다. 우리 경우에는 검색 쿼리 변환기를 말하지만, 데이터베이스 쿼리 변환기를 가리킬 수도 있습니다. 미리 구분하면 혼란을 피할 수 있습니다.
위의 조언 외에 구분자를 사용할 때와 사용하지 않을 때에 대한 강한 규칙은 없습니다. 항목 작성자와 검토자의 몫입니다.
구분자는 짧아야 하지만 단어 하나일 필요는 없습니다. "use cases", "search plugin", "catalog plugin" 같은 예가 있습니다. 사용할 때 구분자는 ({disambiguator}) (괄호로 묶인 용어) 형식을 취하며 제목의 오른쪽에 위치합니다. 구분자는 소문자를 사용해야 합니다.
종합하기 (Putting it together)
제목은 {word} ({disambiguator})처럼 보여야 합니다. 항목은 구분자 외에는 중첩되지 않으며 ##에 위치해야 합니다.
첫 문장 (The first sentence)
첫 문장에는 단어의 "무엇"을 담아야 합니다. "x는 무엇인가?"라는 질문에 답하는 것이 목표입니다. 첫 문장에서 그 단어 자체를 사용하지 마세요. 정의에서 사전의 다른 단어를 사용한다면 Referencing 섹션을 따라 해당 단어를 참조해야 합니다.
같은 맥락에서 여러 의미를 가질 수 있거나 맥락에 경계를 두기 어려운 용어가 있다면, 순서 있는 목록을 사용하여 각 의미를 항목의 별도 섹션으로 구분해야 합니다. 예를 들어,
## Bundle1. A deployment artifact.2. A collection of packages.
추가 문장 (Additional sentences)
단 한 문장으로 정의하고 싶은 것을 완전히 정의하지 못할 수도 있습니다. 더 많은 문장으로 의미를 다듬을 수 있습니다. 다만 너무 깊이 들어가기 시작하면, 그 정보를 플러그인 특정 "concepts" 섹션으로 옮기는 것을 고려해야 합니다. concepts 섹션이 의미 있는 기술적·아키텍처 논의를 추가한다면 두 곳에서 단어가 중복되어도 괜찮습니다.
추가 리소스로 연결 (Linking out to additional resources)
정의하는 용어에 더 좋거나 더 심층적인 정보 소스가 있다면 그곳으로 연결하세요. 여기에는 플러그인 특정 개념 문서, 외부 문서, 핵심 프레임워크 문서가 포함될 수 있습니다.
이러한 링크는 다음과 같이 형식화해야 합니다.
See [the glossary](./glossary.md) for more details.
. 첫 번째 이후의 추가 링크는 필요에 따라 and 또는 or로 연결해야 합니다.
모두 종합하기 (Putting it all together)
## Component (catalog plugin)A software product that is managed in the Backstage [Software Catalog](#software-catalog). A component can be a service, website, library, data pipeline, or any other piece of software managed as a single project. See [the catalog docs](https://backstage.io/docs/features/software-catalog/system-model) for more information.
참조 (Referencing)
사전 내에서 (In the glossary)
자주 참조해야 합니다. 특히 기술 분야에서는 단어가 재귀적으로 정의되며, 일부 용어의 중첩을 풀려면 추가 사전 항목이 필요합니다. 용어가 여러 다른 용어를 기반으로 해도 괜찮습니다. 참조의 목표는 사용자가 정의를 알고 있다고 신뢰할 수 있는 작고 재사용 가능한 단어를 제공하는 것입니다.
본문에서 (In the text)
합리적인 독자가 모를 수 있는 새 단어를 볼 때마다 참조를 추가해야 합니다 (없으면 새 항목을 만들어야 합니다). 현재 글에서 이미 참조를 추가했다면 (사전에서는 그 항목이 될 것임) 새 참조를 추가하지 마세요. 참조는 처음에는 사전을 가리켜야 하며, 추가 정보(개념 페이지 같은 것)가 있다면 사전에 그 페이지로 가는 링크가 있어야 합니다.