Backstage 术语表Glossary词条写作指南从词条结构到引用规范的完整实践【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文基于 Backstage 仓库中 docs/references/writing-a-glossary-entry.md 这一官方写作参考文档系统讲解如何在 Backstage 的 术语表Glossary 中编写高质量词条。你将掌握词条的四段式结构标题、定义句、附加句、外部链接、消除歧义符disambiguator的使用时机、多义词条的组织方式以及词条内与正文中的相互引用规则文中还会结合仓库中已落地的真实词条与引用案例帮助你在为 Backstage 文档贡献术语时写出结构统一、可被读者和搜索引擎稳定解析的内容。术语表在 Backstage 文档体系中的位置Backstage 的术语表是一份集中收录项目内常用术语、缩写与短语的词汇表为整个文档站提供统一的名词定义。在仓库的站点导航配置 mkdocs.yml 中术语表被注册在References一节- References: - Glossary: references/glossary.md术语表的实体内容维护在 docs/references/glossary.md而 docs/references/writing-a-glossary-entry.md 则明确注明其定位——solely serve as reference for how to write glossary entries即一份纯粹面向词条撰写者的规范参考。更重要的是术语表并非孤立存在。仓库中的大量文档都通过相对锚点链接指向术语表中的具体词条例如 docs/permissions/concepts.md 中链接了resource-permission-plugin、condition-permission-plugin、policy-permission-plugin等词条docs/overview/technical-overview.md 链接了entitydocs/tooling/cli/02-build-system.md 链接了monorepo与bundle。这意味着词条标题的质量直接决定这些跨文档引用的可读性与锚点稳定性。词条的基本构成两必两选规范明确一个词条由两个必填项和两个可选项构成标题header——必填是读者发现词条的第一入口定义句a sentence defining what the thing is——必填回答它是什么附加说明句additional sentence(s)——可选补充上下文并给出进一步查阅的线索对外链接links out to additional information——可选指向更深入的资料。以下逐一拆解。标题术语 消除歧义符标题由两部分组成术语本身The term术语应尽可能精简更详细的信息应留给正文而不是标题。可以把它想象成字典词条单词是基本单位多数定义都围绕单个单词展开。同时允许以下几种形态缩略语Acronyms例如API、OAuth形容词 名词的组合例如conditional decision条件决策、backstage frameworkBackstage 框架超过 3 个、至多 4 个词的组合应当慎用——超过这个长度就应该开始做减法把更多内容挪进词条正文。标题中的术语需满足两个硬性格式要求使用 Title Case标题式大小写即每个实词首字母大写使用单数形式。消除歧义符The disambiguator歧义符的目的是区分在不同语境下含义不同的术语。它有两种典型适用场景场景一多个术语共享一个词但语境不同。例如resourcescatalog 插件和 permission 插件都有资源的概念但二者指代的并不是同一事物。通过加歧义符可以清晰划出语境边界。场景二单个术语在不同领域有不同含义。例如Query translators在 Backstage 语境下它指的是_搜索_查询翻译器而读者可能会联想到数据库查询翻译器。提前消除歧义可以避免混淆。歧义符的格式规范如下使用括号包裹形式为({disambiguator})位于标题的右侧使用小写应当简短但不必是单个单词——示例包括use cases、search plugin、catalog plugin。需要特别说明的是规范对何时必须使用歧义符没有硬性规定Beyond the above advice, there are no strong rules for when or when not to use a disambiguator.最终判断交由词条作者与审阅者共同决定。标题的最终形态综合两者标题的格式为{word} ({disambiguator})例如仓库中真实存在的词条标题Component (catalog plugin)Condition (permission plugin)Collator (search plugin)Resource (catalog plugin)与Resource (permission plugin)的配对Kubernetes (Backstage plugin)与Kubernetes (CNCF Project)的配对Namespace (catalog plugin)注意词条之间除了歧义符之外不做嵌套所有词条统一位于##二级标题层级与 docs/references/glossary.md 中实际呈现的结构一致。首句定义回答What is x?词条的第一句话必须回答核心问题——What is x?。它应当直接给出该词的定义the what并且有一条重要的反直觉规则不要在首句中使用被定义的词本身。如果定义中出现了术语表中已有的其他词汇应当按引用Referencing章节的规则为它们建立链接。一个反例如果词条是Plugin首句不应写 A plugin is ...而应像仓库中的真实写法那样绕开这个词本身见 docs/references/glossary.md 中Plugin词条的首句The fundamental building block that adds specific features, functionalities, and integrations to your developer portal.。一词多义用有序列表拆分含义如果一个术语在同一语境下有多重含义或者难以划出语境边界规范建议将每个含义拆分为独立小节并用有序列表组织。原文给出的示例为## Bundle 1. A deployment artifact. 2. A collection of packages.仓库中的真实实现可以验证这一模式。例如 docs/references/glossary.md 中的Backstage词条## Backstage 1. An open source framework for creating and deploying developer portals, originally created at Spotify. Backstage is an incubation-stage open source project of the Cloud Native Computing Foundation (aka CNCF). 2. The Backstage Framework.以及Component (catalog plugin)词条用1.、2.分别列出通用软件单元与Backstage 在 Software Catalog 中管理的软件产品两种含义并在其后补充说明组件与 API 之间的实现/消费关系。附加说明句补充与概念节的分工单句往往无法完整表达一个术语的全部内涵。规范允许使用更多的句子来充实含义但如果你发现自己越写越深、进入了某个插件的技术细节就应当停下来考虑把这类内容重新安置到插件专属的concepts概念章节中。规范同时明确同一个词允许在术语表和概念节中重复出现只要概念节能提供有意义的架构或技术讨论即可。换句话说术语表词条负责这个术语是什么的精确定义插件概念节负责这个术语在其架构中如何工作的深度展开两者通过词条中的对外链接衔接而非互相复制。对外链接把读者导向更深的资料如果被定义的术语存在更好、更深入的信息来源应当链接过去。可选来源包括插件专属的概念文档、外部文档、或核心框架文档。链接的推荐格式如下See [the glossary](https://link.gitcode.com/i/0937ecbf5c4c0dab1b6bdc0f83459a2b) for more details.超过一条附加链接时用and或or按需连接。仓库中大量真实词条遵循了这一模式例如 docs/references/glossary.md 中Software Catalog词条链接到系统模型、生命周期等概念文档Policy (permission plugin)词条链接到权限框架的概念页与写作指南Indexer (search plugin)词条以编号列表解释搜索索引数据流后点名plugin-search-backend-node包负责编排整个索引过程。综合示例完整词条长什么样规范给出的完整示例为## 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.对照仓库中的真实词条docs/references/glossary.md 的Component (catalog plugin)可以看到它进一步演进了这一结构以有序列表给出两条定义补充组件与 API 的相互实现/消费关系并链接到 docs/features/software-catalog/system-model.md 对应的系统模型章节。若在你的文章中引用该词条请使用仓库根目录下的相对路径形式Software Catalog 系统模型权限框架概念引用规则Referencing让词条像字典一样可复用引用是本规范中方法论色彩最浓的部分分为两个层面。词条内引用应当高频使用引用。技术词汇的定义天然具有递归性——解开一个术语往往需要依赖其他术语。规范明确词条定义可以建立在多个其他词条之上这正是允许且鼓励的。引用的目标是为读者提供小而可复用、可以确信读者已经掌握其定义的词汇单元。以 docs/references/glossary.md 中的Policy (permission plugin)词条为例其定义中先后引用了authorization、resource等多个词条构成了一条可追溯的定义链。正文引用在文档正文中规则同样明确每当出现一个合理读者可能不认识的新词时就应当引用它若该词条尚不存在则应考虑新建词条如果在当前段落中已经引用过一次就不要再重复添加引用引用应首先指向术语表如果存在更深层的资料例如概念页术语表词条本身应包含指向该页面的链接。这样形成的链路是正文 → 术语表词条 → 概念文档既保证正文简洁又让读者有逐级深入的路径。仓库中的落地验证词条格式在仓库中的实际形态对照 docs/references/glossary.md 的 80 余个词条可以确认规范中的每一条建议都已落地所有词条统一使用##标题带歧义符的词条严格遵循Word (disambiguator)小写括号格式多义词条使用有序列表如Backstage、Bundle、Component (catalog plugin)、Domain、Entity、Package跨文档锚点如#resource-permission-plugin、#software-templates、#kind-namespace-name-triplet通过 HTML 锚点属性显式声明保证链接稳定部分词条如Name明确标注To be completed.说明词条库本身也在持续演进中。其他文档如何消费术语表术语表的引用价值体现在仓库文档的广泛链接上。以下均为已确认存在的引用点可直接作为写作时的参考范例docs/permissions/concepts.md 引用software-templates、authorization、plugin、permission-permission-plugin、resource-permission-plugin、rule-permission-plugin、condition-permission-plugin等词条docs/overview/technical-overview.md 引用entity词条解释系统模型docs/tooling/cli/02-build-system.md 引用monorepo、bundle、package等构建相关词条docs/landing-page/doc-landing-page.md 在落地页中直接收录了 Glossary 的导航入口。这种正文 → 词条 → 概念文档的引用结构与规范的Referencing章节完全一致。与文档风格指南的协同词条写作并非孤立规范它与仓库的 docs/contribute/doc-style-guide.md 共同构成文档贡献约束。写作词条时尤其需要注意风格指南中的以下几点首次出现缩略语时拼写全称并加括号例如 OpenID Connect (OIDC)——这与词条标题中使用缩略语如ID Token、JSON Web Token (aka JWT)的实践互为补充新引入的术语用斜体标记如plugin与术语表词条首句不使用被定义词的规则配合避免正文与词条定义互相重复使用现在时态与主动语态保持定义句简洁避免e.g.、i.e.等拉丁缩写etc.除外用 For example, 与 That is, 替代。快速自查清单撰写或审阅词条时可以对照以下清单逐项检查检查项要求标题层级统一使用##不做嵌套术语长度尽量为单个单词或缩略语不超过 3–4 个词术语格式Title Case、单数形式歧义符格式({disambiguator})小写置于标题右侧必要时才使用首句定义回答What is x?且不使用被定义的词本身一词多义用有序列表拆分各含义附加句补充上下文内容过深时移入插件概念节对外链接首选概念文档多条链接用and/or连接词条内引用引用术语表中已有的其他词条构建可复用定义链正文引用新词首次出现即引用同一段落不重复引用引用先指向术语表风格遵循 docs/contribute/doc-style-guide.md 的时态、语态与术语约定遵循以上规范编写的词条能够让术语表保持字典式的一致性与可检索性也让 Backstage 整个文档体系中的跨文档链接长期稳定。如果你正在为 Backstage 贡献文档docs/references/glossary.md 是查看完整词条实践的最佳样本。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage 术语表（Glossary）词条写作指南：从词条结构到引用规范的完整实践
Backstage 术语表Glossary词条写作指南从词条结构到引用规范的完整实践【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文基于 Backstage 仓库中 docs/references/writing-a-glossary-entry.md 这一官方写作参考文档系统讲解如何在 Backstage 的 术语表Glossary 中编写高质量词条。你将掌握词条的四段式结构标题、定义句、附加句、外部链接、消除歧义符disambiguator的使用时机、多义词条的组织方式以及词条内与正文中的相互引用规则文中还会结合仓库中已落地的真实词条与引用案例帮助你在为 Backstage 文档贡献术语时写出结构统一、可被读者和搜索引擎稳定解析的内容。术语表在 Backstage 文档体系中的位置Backstage 的术语表是一份集中收录项目内常用术语、缩写与短语的词汇表为整个文档站提供统一的名词定义。在仓库的站点导航配置 mkdocs.yml 中术语表被注册在References一节- References: - Glossary: references/glossary.md术语表的实体内容维护在 docs/references/glossary.md而 docs/references/writing-a-glossary-entry.md 则明确注明其定位——solely serve as reference for how to write glossary entries即一份纯粹面向词条撰写者的规范参考。更重要的是术语表并非孤立存在。仓库中的大量文档都通过相对锚点链接指向术语表中的具体词条例如 docs/permissions/concepts.md 中链接了resource-permission-plugin、condition-permission-plugin、policy-permission-plugin等词条docs/overview/technical-overview.md 链接了entitydocs/tooling/cli/02-build-system.md 链接了monorepo与bundle。这意味着词条标题的质量直接决定这些跨文档引用的可读性与锚点稳定性。词条的基本构成两必两选规范明确一个词条由两个必填项和两个可选项构成标题header——必填是读者发现词条的第一入口定义句a sentence defining what the thing is——必填回答它是什么附加说明句additional sentence(s)——可选补充上下文并给出进一步查阅的线索对外链接links out to additional information——可选指向更深入的资料。以下逐一拆解。标题术语 消除歧义符标题由两部分组成术语本身The term术语应尽可能精简更详细的信息应留给正文而不是标题。可以把它想象成字典词条单词是基本单位多数定义都围绕单个单词展开。同时允许以下几种形态缩略语Acronyms例如API、OAuth形容词 名词的组合例如conditional decision条件决策、backstage frameworkBackstage 框架超过 3 个、至多 4 个词的组合应当慎用——超过这个长度就应该开始做减法把更多内容挪进词条正文。标题中的术语需满足两个硬性格式要求使用 Title Case标题式大小写即每个实词首字母大写使用单数形式。消除歧义符The disambiguator歧义符的目的是区分在不同语境下含义不同的术语。它有两种典型适用场景场景一多个术语共享一个词但语境不同。例如resourcescatalog 插件和 permission 插件都有资源的概念但二者指代的并不是同一事物。通过加歧义符可以清晰划出语境边界。场景二单个术语在不同领域有不同含义。例如Query translators在 Backstage 语境下它指的是_搜索_查询翻译器而读者可能会联想到数据库查询翻译器。提前消除歧义可以避免混淆。歧义符的格式规范如下使用括号包裹形式为({disambiguator})位于标题的右侧使用小写应当简短但不必是单个单词——示例包括use cases、search plugin、catalog plugin。需要特别说明的是规范对何时必须使用歧义符没有硬性规定Beyond the above advice, there are no strong rules for when or when not to use a disambiguator.最终判断交由词条作者与审阅者共同决定。标题的最终形态综合两者标题的格式为{word} ({disambiguator})例如仓库中真实存在的词条标题Component (catalog plugin)Condition (permission plugin)Collator (search plugin)Resource (catalog plugin)与Resource (permission plugin)的配对Kubernetes (Backstage plugin)与Kubernetes (CNCF Project)的配对Namespace (catalog plugin)注意词条之间除了歧义符之外不做嵌套所有词条统一位于##二级标题层级与 docs/references/glossary.md 中实际呈现的结构一致。首句定义回答What is x?词条的第一句话必须回答核心问题——What is x?。它应当直接给出该词的定义the what并且有一条重要的反直觉规则不要在首句中使用被定义的词本身。如果定义中出现了术语表中已有的其他词汇应当按引用Referencing章节的规则为它们建立链接。一个反例如果词条是Plugin首句不应写 A plugin is ...而应像仓库中的真实写法那样绕开这个词本身见 docs/references/glossary.md 中Plugin词条的首句The fundamental building block that adds specific features, functionalities, and integrations to your developer portal.。一词多义用有序列表拆分含义如果一个术语在同一语境下有多重含义或者难以划出语境边界规范建议将每个含义拆分为独立小节并用有序列表组织。原文给出的示例为## Bundle 1. A deployment artifact. 2. A collection of packages.仓库中的真实实现可以验证这一模式。例如 docs/references/glossary.md 中的Backstage词条## Backstage 1. An open source framework for creating and deploying developer portals, originally created at Spotify. Backstage is an incubation-stage open source project of the Cloud Native Computing Foundation (aka CNCF). 2. The Backstage Framework.以及Component (catalog plugin)词条用1.、2.分别列出通用软件单元与Backstage 在 Software Catalog 中管理的软件产品两种含义并在其后补充说明组件与 API 之间的实现/消费关系。附加说明句补充与概念节的分工单句往往无法完整表达一个术语的全部内涵。规范允许使用更多的句子来充实含义但如果你发现自己越写越深、进入了某个插件的技术细节就应当停下来考虑把这类内容重新安置到插件专属的concepts概念章节中。规范同时明确同一个词允许在术语表和概念节中重复出现只要概念节能提供有意义的架构或技术讨论即可。换句话说术语表词条负责这个术语是什么的精确定义插件概念节负责这个术语在其架构中如何工作的深度展开两者通过词条中的对外链接衔接而非互相复制。对外链接把读者导向更深的资料如果被定义的术语存在更好、更深入的信息来源应当链接过去。可选来源包括插件专属的概念文档、外部文档、或核心框架文档。链接的推荐格式如下See [the glossary](https://link.gitcode.com/i/0937ecbf5c4c0dab1b6bdc0f83459a2b) for more details.超过一条附加链接时用and或or按需连接。仓库中大量真实词条遵循了这一模式例如 docs/references/glossary.md 中Software Catalog词条链接到系统模型、生命周期等概念文档Policy (permission plugin)词条链接到权限框架的概念页与写作指南Indexer (search plugin)词条以编号列表解释搜索索引数据流后点名plugin-search-backend-node包负责编排整个索引过程。综合示例完整词条长什么样规范给出的完整示例为## 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.对照仓库中的真实词条docs/references/glossary.md 的Component (catalog plugin)可以看到它进一步演进了这一结构以有序列表给出两条定义补充组件与 API 的相互实现/消费关系并链接到 docs/features/software-catalog/system-model.md 对应的系统模型章节。若在你的文章中引用该词条请使用仓库根目录下的相对路径形式Software Catalog 系统模型权限框架概念引用规则Referencing让词条像字典一样可复用引用是本规范中方法论色彩最浓的部分分为两个层面。词条内引用应当高频使用引用。技术词汇的定义天然具有递归性——解开一个术语往往需要依赖其他术语。规范明确词条定义可以建立在多个其他词条之上这正是允许且鼓励的。引用的目标是为读者提供小而可复用、可以确信读者已经掌握其定义的词汇单元。以 docs/references/glossary.md 中的Policy (permission plugin)词条为例其定义中先后引用了authorization、resource等多个词条构成了一条可追溯的定义链。正文引用在文档正文中规则同样明确每当出现一个合理读者可能不认识的新词时就应当引用它若该词条尚不存在则应考虑新建词条如果在当前段落中已经引用过一次就不要再重复添加引用引用应首先指向术语表如果存在更深层的资料例如概念页术语表词条本身应包含指向该页面的链接。这样形成的链路是正文 → 术语表词条 → 概念文档既保证正文简洁又让读者有逐级深入的路径。仓库中的落地验证词条格式在仓库中的实际形态对照 docs/references/glossary.md 的 80 余个词条可以确认规范中的每一条建议都已落地所有词条统一使用##标题带歧义符的词条严格遵循Word (disambiguator)小写括号格式多义词条使用有序列表如Backstage、Bundle、Component (catalog plugin)、Domain、Entity、Package跨文档锚点如#resource-permission-plugin、#software-templates、#kind-namespace-name-triplet通过 HTML 锚点属性显式声明保证链接稳定部分词条如Name明确标注To be completed.说明词条库本身也在持续演进中。其他文档如何消费术语表术语表的引用价值体现在仓库文档的广泛链接上。以下均为已确认存在的引用点可直接作为写作时的参考范例docs/permissions/concepts.md 引用software-templates、authorization、plugin、permission-permission-plugin、resource-permission-plugin、rule-permission-plugin、condition-permission-plugin等词条docs/overview/technical-overview.md 引用entity词条解释系统模型docs/tooling/cli/02-build-system.md 引用monorepo、bundle、package等构建相关词条docs/landing-page/doc-landing-page.md 在落地页中直接收录了 Glossary 的导航入口。这种正文 → 词条 → 概念文档的引用结构与规范的Referencing章节完全一致。与文档风格指南的协同词条写作并非孤立规范它与仓库的 docs/contribute/doc-style-guide.md 共同构成文档贡献约束。写作词条时尤其需要注意风格指南中的以下几点首次出现缩略语时拼写全称并加括号例如 OpenID Connect (OIDC)——这与词条标题中使用缩略语如ID Token、JSON Web Token (aka JWT)的实践互为补充新引入的术语用斜体标记如plugin与术语表词条首句不使用被定义词的规则配合避免正文与词条定义互相重复使用现在时态与主动语态保持定义句简洁避免e.g.、i.e.等拉丁缩写etc.除外用 For example, 与 That is, 替代。快速自查清单撰写或审阅词条时可以对照以下清单逐项检查检查项要求标题层级统一使用##不做嵌套术语长度尽量为单个单词或缩略语不超过 3–4 个词术语格式Title Case、单数形式歧义符格式({disambiguator})小写置于标题右侧必要时才使用首句定义回答What is x?且不使用被定义的词本身一词多义用有序列表拆分各含义附加句补充上下文内容过深时移入插件概念节对外链接首选概念文档多条链接用and/or连接词条内引用引用术语表中已有的其他词条构建可复用定义链正文引用新词首次出现即引用同一段落不重复引用引用先指向术语表风格遵循 docs/contribute/doc-style-guide.md 的时态、语态与术语约定遵循以上规范编写的词条能够让术语表保持字典式的一致性与可检索性也让 Backstage 整个文档体系中的跨文档链接长期稳定。如果你正在为 Backstage 贡献文档docs/references/glossary.md 是查看完整词条实践的最佳样本。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考