Backstage 文档写作风格指南从语言规范到源码工具链的完整实践【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南系统梳理 Backstage 开源仓库的文档写作规范覆盖语言与语气、Markdown 格式标准、代码片段约定、Admonitions 与 Accordions 用法、内容最佳实践以及官方词汇表并结合仓库中的 Docusaurus 站点配置、Vale 文档检查脚本 与 链接验证脚本 展示这些规范如何被工具化落地。阅读后你将掌握一套可直接用于 Backstage 文档贡献以及大型开源项目文档协作的写作与审查标准。文档指南的定位与适用场景Backstage 的官方文档风格指南位于 docs/contribute/doc-style-guide.md它的定位非常明确这是一组 guideline指南而非硬性规则。编写文档时应运用最佳判断力如果发现指南本身需要改进欢迎通过 Pull Request 提议修改。该指南服务于两类读者Backstage 贡献者在提交文档改动尤其是 Markdown 文件时需要遵循的写作与格式约定。仓库的 CONTRIBUTING.md 明确指出文档贡献是参与 Backstage 的最佳起点之一并推荐先通读本风格指南见 CONTRIBUTING.md 文档贡献章节。在文档站点写作的任何参与者包括插件作者、维护者以及撰写教程、词汇表、架构决策记录ADR的社区成员。语言美式英语与文档站点Backstage 文档统一使用U.S. English美式英语的拼写和语法。这意味着诸如color、behavior、center这类美式拼写是标准写法。文档站点本身由Docusaurus构建使用标准 Markdown并支持 Docusaurus 特有的扩展特性如 admonitions。这一点可以从仓库根目录的 microsite/docusaurus.config.ts 得到印证文档目录被直接配置为../docs配置位置并启用了 Mermaid、OpenAPI 文档等能力。因此任何贡献到docs/的 Markdown 都会经过 Docusaurus 的解析与渲染管线。语气像一位知识渊博的同事指南对文档语气给出了五条核心原则。整体目标是亲切approachable、专业professional、有帮助helpful。写作时把自己想象成一位知识渊博的同事正在向一位熟悉软件开发、但刚接触该主题的同行解释问题。原则说明友好但不随意避免俚语、可能无法跨文化翻译的幽默以及过度热情的表达温暖、直截了当的语气最佳尊重读者的时间直奔主题需要长篇解释时提供足够细节但不用填充内容凑字数鼓励但不居高临下假定读者有能力理解避免 as everyone knows众所周知或 obviously显然之类的措辞包容性使用中性性别语言避免可能无法被全球读者理解的特定文化指代面向国际受众写作精确使用 Backstage 概念的准确技术术语首次引入新术语时必须给出定义文档格式标准用粗体标注界面元素提到按钮、菜单项等界面元素时使用粗体不要用引号。正确错误ClickFork.Click Fork.SelectOther.Select Other.用斜体定义或引入新术语首次定义或引入新术语时使用斜体而不是粗体或引号。正确错误Apluginis a modular extension ...A plugin is a modular extension ...These components form thebackend system.These components form thebackend system.文件名、目录与路径使用代码样式所有文件名、目录路径必须用反引号包裹。正确错误Open theapp-config.yamlfile.Open the app-config.yaml file.Go to the/pluginsdirectory.Go to the /plugins directory.Open thepackages/backend/src/index.tsfile.Open the packages/backend/src/index.ts file.行内代码与命令使用代码样式正确错误Theyarn startcommand starts the app.The yarn start command starts the app.Runyarn installfrom the project root.Run yarn install from the project root.Use single backticks to enclose inline code, for exampleconst x true.Use bold or italics for inline code, for exampleconst x true.Enclose code samples with triple backticks.Enclose code samples with any other syntax.Use meaningful variable names that have context.Use variable names such asfoo,bar, andbaz.包名与 API 引用使用代码样式涉及包名、函数名、配置字段时一律使用反引号正确错误Install thebackstage/core-plugin-apipackage.Install the backstage/core-plugin-api package.ThecreateRouterfunction creates a new router.The createRouter function creates a new router.Set the value of thebackend.baseUrlfield in the config file.Set the value of the backend.baseUrl field in the config file.用尖括号表示占位符占位符使用尖括号并在文字中说明它代表什么yarn workspace backstage/plugin-plugin-name start引号内标点遵循国际标准句号放在引号外英式/国际习惯除非标点本来就是引文的一部分正确错误Events are recorded with an associated stage.Events are recorded with an associated stage.The copy is called a fork.The copy is called a fork.代码片段格式不要包含命令提示符代码块中只写命令本身不要带上$等提示符正确错误yarn install$ yarn install命令与输出分离命令与输出分别放在独立代码块中并用文字引导yarn start输出类似于[0] webpack output is served from / [1] Loaded config from app-config.yaml使用合适的语言标签围栏代码块必须使用正确的语言标识符ts或typescriptTypeScript 代码yamlYAML 配置shellshell 命令log命令输出shell-session同时包含提示符与输出的对话记录diffchangeset 变更text其他都不合适时如目录树一个容易忽略的细节标识符必须是 Prism 能识别的语言凡是超出 Docusaurus 默认内置集合的语言都必须在站点配置的additionalLanguages中登记否则代码块不会报错但会静默失去语法高亮。Backstage 站点的实际配置如下microsite/docusaurus.config.ts#L678-L704prism: { theme: backstageTheme, // Supported languages: https://prismjs.com/#supported-languages additionalLanguages: [docker, bash, log, shell-session], magicComments: [ // ...高亮行、增删行注释约定 ], },可以看到docker、bash、log、shell-session被显式加入高亮支持列表同时magicComments还定义了highlight-next-line、highlight-start/highlight-end、highlight-add-*、highlight-remove-*等注释约定用于在代码块中标记重点行。Admonitions警示块的正确用法Backstage 文档使用 Docusaurus admonitions 作为提示框四种类型各司其职:::note补充性信息:::tip有帮助的建议:::caution潜在陷阱:::danger可能导致数据丢失或安全问题的操作基本语法admonition 内部支持 Markdown:::note You can use _Markdown_ inside admonitions. :::自定义标题把标题放在方括号中紧跟在类型后。需要注意旧式的类型后空格直接写标题写法已经失效——那样写的话 admonition 会渲染成纯文本:::tip[Browser window didnt open] Navigate to http://localhost:3000 yourself. :::使用注意点仅在标题能补充类型本身未表达的信息时才添加标题一个:::note配上Note标题纯属噪音应省略。保持简短聚焦每个 admonition 只讲一个清晰要点如果需要写多个段落考虑是否应移入正文。避免连续堆叠多个 admonition过多提示框会稀释影响力。如果某个小节超过两个 admonition应重构内容把大部分信息放回普通段落。Accordions可折叠区块使用 HTML 的details和summary元素创建可折叠区块适合常见问题、冗长的参考表格或会打断阅读流程的补充内容details summarySummary text visible when collapsed/summary Content inside the accordion. You can use **Markdown** here, including code blocks, lists, and other formatting. /details两个关键细节在summary标签之后、/details闭合标签之前各留一个空行否则内部的 Markdown 内容无法正确渲染。summary内部的代码一律使用反引号而不是 HTML 的code标签——反引号在 summary 元素中能正确渲染且与全文其他 Markdown 的写法保持一致。Markdown 元素规范换行块级内容标题、列表、图片、代码块等之间用一个空行分隔段落源码按合理的行宽手动换行这能让 diff 更易审查也有助于后续本地化翻译。标题与标题大小写正确错误使用有序的标题层级为内容提供有意义的提纲除非绝对必要不要使用 46 级标题标题使用 sentence case如Extend the catalog model标题使用 Title Case如Extend The Catalog Model用井号#表示标题用下划线---或表示标题段落尽量保持段落不超过 6 个句子避免大段无断落的文字墙。需要水平分割线时使用三个连字符---但不要把它当作装饰。链接正确错误使用描述性文字写超链接如 See Getting Started for details.使用含义模糊的链接文字如 See here for details.写 Markdown 风格链接[link text](https://link.gitcode.com/i/28ffea7b4ae15ef3df35390a80c2d30d)写 HTML 风格链接或创建新标签页打开的链接给裸地址加标记https://example.com直接粘贴裸地址https://example.com描述性链接文字尤为重要使用屏幕阅读器的用户常常通过逐条列出链接来浏览页面the Kubernetes configuration能告诉他们链接去向而裸地址做不到。当想直接展示地址本身时语法取决于文件扩展名在.md文件中可以用尖括号或 Markdown 链接。在.mdx文件中必须用 Markdown 链接——尖括号在.mdx中不合法会导致构建失败。仓库对链接的自动化校验也印证了这些约定脚本 scripts/verify-links.js 会遍历仓库中的 Markdown提取所有标题锚点extractHeadingAnchors并处理重复标题的-1、-2后缀以校验页内锚点同时用INVISIBLE_CHAR_PATTERN拦截 URL 中的零宽字符等不可见 Unicode 字符见 verify-links.js#L27-L90。列表如果列表中有任何一项是完整句子则每项都以句号结尾为保证一致性要么全部是完整句子要么全部不是。有序列表统一使用数字1.。无序列表使用-。每个列表后留一个空行。嵌套列表缩进两个空格。步骤序列使用编号列表而不是用 First、Then、Finally 的散文式叙述——编号列表更易扫读、顺序更明确也方便读者指代具体步骤正确错误1) Install the package. 2) Run the migration. 3) Start the server.First, install the package. Then, run the migration. Finally, start the server.表格使用带清晰列头的 Markdown 表格保持内容简洁。对于大量结构化数据考虑改用列表或拆分独立小节而不是塞进一张巨型表格。内容最佳实践首次出现时拼写缩写首次使用缩写时先写出全称并在括号中给出缩写之后可以单独使用缩写正确错误Software Development Kit (SDK)SDK (without ever defining it)Role-Based Access Control (RBAC) ... configure RBAC ...RBAC ... configure RBAC ...Hyper Text Markup Language (HTML)HTML (on first use without expansion)例外URL、API、HTML 这类目标读者软件开发者普遍熟知的缩写无需拼写全称。使用现在时正确错误This command starts a proxy.This command will start a proxy.The plugin provides a catalog page.The plugin will provide a catalog page.例外当必须表达正确含义时才使用将来时或过去时。使用主动语态正确错误You can explore the API using a browser.The API can be explored using a browser.The YAML file specifies the base URL.The base URL is specified in the YAML file.例外如果主动语态会导致表达笨拙可以使用被动语态。使用简单直接的语言正确错误To create a plugin, ...In order to create a plugin, ...See the configuration file.Please see the configuration file.View the catalog entities.With this next command, well view the catalog entities.以 you 称呼读者正确错误You can create a plugin by ...Well create a plugin by ...In the preceding output, you can see ...In the preceding output, we can see ...避免拉丁短语优先使用英文表达替代拉丁缩写正确错误For example, ...e.g., ...That is, ...i.e., ...例外表示等等时可使用 etc.。应避免的写作模式审慎使用 wewe 在教程和引导式文章中是可接受的此时它表示你和我一起完成这个过程。但当它指代不明是 Backstage 项目、维护者还是读者团队时应避免可以避免Next, we need to add the backend package.We provide a new feature ...We can verify this by runningyarn start.In version 1.25, we have added ...避免行话和习语部分读者以英语为第二语言避免行话和习语有助于他们理解正确错误Internally, ...Under the hood, ...Create a new plugin.Spin up a new plugin.避免关于未来的声明不做关于未来的承诺或暗示。如果必须谈论实验性功能请明确标注它是实验性的。避免很快过时的声明避免使用 currently、new 这类时效性强的词——今天的新功能几个月后可能就不再新了正确错误In version 1.25, ...In the current version, ...The search feature provides ...The new search feature provides ...避免假定读者理解程度的词避免 just、simply、easy、easily、simple 这类不增加价值的词正确错误Include one command in ...Include just one command in ...Run the container ...Simply run the container ...You can remove ...You can easily remove ...These steps ...These simple steps ...Backstage 专用词汇表以下术语在全站必须保持一致用法术语用法Backstage始终大写。plugin指概念时小写指具体包时用代码样式例如backstage/plugin-catalog。Software Catalog作为产品名时大写泛指概念时用小写 catalog。Software Templates作为产品名时大写。TechDocs一个单词驼峰式。Scaffolder作为产品名时大写。app-config使用代码样式app-config.yaml。open source两个单词小写句首除外。backend system指 Backstage 后端框架时小写。通用词汇表术语用法GitHub文档中使用 GitHub代码中使用github小写。此外仓库还提供了词汇表条目的专门写作规范 docs/references/writing-a-glossary-entry.md说明词条由标题术语 消歧符、首句定义、可选的补充句与外部链接组成例如用{word} ({disambiguator})的标题形式区分不同语境下的同名术语——这可以视为本风格指南在术语一致性上的延伸落地。规范的工具化落地文档质量如何被自动检查风格指南不只是纸面约定Backstage 用一套脚本将其落地为 CI 可执行的检查Vale 语言检查scripts/check-docs-quality.js 调用 Vale linter配置文件为根目录的 .vale.ini其中StylesPath .github/vale、Vocab Backstage文档库即来自本风格指南中的词汇表。脚本runVale会以--config指定配置并逐文件运行check-docs-quality.js#L83-L103ciCheck则在 CI 中只对 PR 改动的.md文件执行检查并把 Vale 输出转成 GitHub Actions 注解与 eslint 风格的行内报告check-docs-quality.js#L105-L129。需要新增专业词汇时把词加入.github/vale/config/vocabularies/Backstage/accept.txt即可这一点在 CONTRIBUTING.md 的 Vale 说明中也有提及。链接验证scripts/verify-links.js 负责扫描 Markdown 链接验证目标文件与标题锚点是否存在自动处理{#custom-id}显式锚点和 GitHub/Docusaurus 兼容的 slug 化规则并拦截 URL 中的不可见 Unicode 字符防止出现看起来正常但点击失效的链接。本地执行入口在 CONTRIBUTING.md 的文档贡献部分L126、L199明确给出了本地命令yarn run lint:docs即yarn lint:docs # Lint all the Markdown files它运行上述文档质量检查。注意 Vale 需要单独安装并保证全局命令可访问。对于想要为 Backstage 提交文档的开发者推荐的工作流是先在本地运行yarn lint:docs通过 Vale 与链接检查再对照本指南逐项自查格式与措辞若 Vale 对某个代码引用报错用反引号包住该引用即可若是需要认可的专业术语则提交到 accept.txt 词汇表。小结Backstage 文档风格指南的核心可以浓缩为三句话用准确、简洁、友好的英文写作把一切代码与命令相关的内容用反引号标注让自动化工具Vale 与链接检查替你守住格式底线。从语言语气到格式细节再到词汇表和工具链这套规范既保证了百万级文档站点docs 目录 Docusaurus 渲染的一致性也让每一位贡献者的改动都能被快速审查和合并。无论你是贡献 Backstage 文档还是为自己所在团队搭建文档规范这份指南都值得直接借鉴。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage 文档写作风格指南：从语言规范到源码工具链的完整实践
Backstage 文档写作风格指南从语言规范到源码工具链的完整实践【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南系统梳理 Backstage 开源仓库的文档写作规范覆盖语言与语气、Markdown 格式标准、代码片段约定、Admonitions 与 Accordions 用法、内容最佳实践以及官方词汇表并结合仓库中的 Docusaurus 站点配置、Vale 文档检查脚本 与 链接验证脚本 展示这些规范如何被工具化落地。阅读后你将掌握一套可直接用于 Backstage 文档贡献以及大型开源项目文档协作的写作与审查标准。文档指南的定位与适用场景Backstage 的官方文档风格指南位于 docs/contribute/doc-style-guide.md它的定位非常明确这是一组 guideline指南而非硬性规则。编写文档时应运用最佳判断力如果发现指南本身需要改进欢迎通过 Pull Request 提议修改。该指南服务于两类读者Backstage 贡献者在提交文档改动尤其是 Markdown 文件时需要遵循的写作与格式约定。仓库的 CONTRIBUTING.md 明确指出文档贡献是参与 Backstage 的最佳起点之一并推荐先通读本风格指南见 CONTRIBUTING.md 文档贡献章节。在文档站点写作的任何参与者包括插件作者、维护者以及撰写教程、词汇表、架构决策记录ADR的社区成员。语言美式英语与文档站点Backstage 文档统一使用U.S. English美式英语的拼写和语法。这意味着诸如color、behavior、center这类美式拼写是标准写法。文档站点本身由Docusaurus构建使用标准 Markdown并支持 Docusaurus 特有的扩展特性如 admonitions。这一点可以从仓库根目录的 microsite/docusaurus.config.ts 得到印证文档目录被直接配置为../docs配置位置并启用了 Mermaid、OpenAPI 文档等能力。因此任何贡献到docs/的 Markdown 都会经过 Docusaurus 的解析与渲染管线。语气像一位知识渊博的同事指南对文档语气给出了五条核心原则。整体目标是亲切approachable、专业professional、有帮助helpful。写作时把自己想象成一位知识渊博的同事正在向一位熟悉软件开发、但刚接触该主题的同行解释问题。原则说明友好但不随意避免俚语、可能无法跨文化翻译的幽默以及过度热情的表达温暖、直截了当的语气最佳尊重读者的时间直奔主题需要长篇解释时提供足够细节但不用填充内容凑字数鼓励但不居高临下假定读者有能力理解避免 as everyone knows众所周知或 obviously显然之类的措辞包容性使用中性性别语言避免可能无法被全球读者理解的特定文化指代面向国际受众写作精确使用 Backstage 概念的准确技术术语首次引入新术语时必须给出定义文档格式标准用粗体标注界面元素提到按钮、菜单项等界面元素时使用粗体不要用引号。正确错误ClickFork.Click Fork.SelectOther.Select Other.用斜体定义或引入新术语首次定义或引入新术语时使用斜体而不是粗体或引号。正确错误Apluginis a modular extension ...A plugin is a modular extension ...These components form thebackend system.These components form thebackend system.文件名、目录与路径使用代码样式所有文件名、目录路径必须用反引号包裹。正确错误Open theapp-config.yamlfile.Open the app-config.yaml file.Go to the/pluginsdirectory.Go to the /plugins directory.Open thepackages/backend/src/index.tsfile.Open the packages/backend/src/index.ts file.行内代码与命令使用代码样式正确错误Theyarn startcommand starts the app.The yarn start command starts the app.Runyarn installfrom the project root.Run yarn install from the project root.Use single backticks to enclose inline code, for exampleconst x true.Use bold or italics for inline code, for exampleconst x true.Enclose code samples with triple backticks.Enclose code samples with any other syntax.Use meaningful variable names that have context.Use variable names such asfoo,bar, andbaz.包名与 API 引用使用代码样式涉及包名、函数名、配置字段时一律使用反引号正确错误Install thebackstage/core-plugin-apipackage.Install the backstage/core-plugin-api package.ThecreateRouterfunction creates a new router.The createRouter function creates a new router.Set the value of thebackend.baseUrlfield in the config file.Set the value of the backend.baseUrl field in the config file.用尖括号表示占位符占位符使用尖括号并在文字中说明它代表什么yarn workspace backstage/plugin-plugin-name start引号内标点遵循国际标准句号放在引号外英式/国际习惯除非标点本来就是引文的一部分正确错误Events are recorded with an associated stage.Events are recorded with an associated stage.The copy is called a fork.The copy is called a fork.代码片段格式不要包含命令提示符代码块中只写命令本身不要带上$等提示符正确错误yarn install$ yarn install命令与输出分离命令与输出分别放在独立代码块中并用文字引导yarn start输出类似于[0] webpack output is served from / [1] Loaded config from app-config.yaml使用合适的语言标签围栏代码块必须使用正确的语言标识符ts或typescriptTypeScript 代码yamlYAML 配置shellshell 命令log命令输出shell-session同时包含提示符与输出的对话记录diffchangeset 变更text其他都不合适时如目录树一个容易忽略的细节标识符必须是 Prism 能识别的语言凡是超出 Docusaurus 默认内置集合的语言都必须在站点配置的additionalLanguages中登记否则代码块不会报错但会静默失去语法高亮。Backstage 站点的实际配置如下microsite/docusaurus.config.ts#L678-L704prism: { theme: backstageTheme, // Supported languages: https://prismjs.com/#supported-languages additionalLanguages: [docker, bash, log, shell-session], magicComments: [ // ...高亮行、增删行注释约定 ], },可以看到docker、bash、log、shell-session被显式加入高亮支持列表同时magicComments还定义了highlight-next-line、highlight-start/highlight-end、highlight-add-*、highlight-remove-*等注释约定用于在代码块中标记重点行。Admonitions警示块的正确用法Backstage 文档使用 Docusaurus admonitions 作为提示框四种类型各司其职:::note补充性信息:::tip有帮助的建议:::caution潜在陷阱:::danger可能导致数据丢失或安全问题的操作基本语法admonition 内部支持 Markdown:::note You can use _Markdown_ inside admonitions. :::自定义标题把标题放在方括号中紧跟在类型后。需要注意旧式的类型后空格直接写标题写法已经失效——那样写的话 admonition 会渲染成纯文本:::tip[Browser window didnt open] Navigate to http://localhost:3000 yourself. :::使用注意点仅在标题能补充类型本身未表达的信息时才添加标题一个:::note配上Note标题纯属噪音应省略。保持简短聚焦每个 admonition 只讲一个清晰要点如果需要写多个段落考虑是否应移入正文。避免连续堆叠多个 admonition过多提示框会稀释影响力。如果某个小节超过两个 admonition应重构内容把大部分信息放回普通段落。Accordions可折叠区块使用 HTML 的details和summary元素创建可折叠区块适合常见问题、冗长的参考表格或会打断阅读流程的补充内容details summarySummary text visible when collapsed/summary Content inside the accordion. You can use **Markdown** here, including code blocks, lists, and other formatting. /details两个关键细节在summary标签之后、/details闭合标签之前各留一个空行否则内部的 Markdown 内容无法正确渲染。summary内部的代码一律使用反引号而不是 HTML 的code标签——反引号在 summary 元素中能正确渲染且与全文其他 Markdown 的写法保持一致。Markdown 元素规范换行块级内容标题、列表、图片、代码块等之间用一个空行分隔段落源码按合理的行宽手动换行这能让 diff 更易审查也有助于后续本地化翻译。标题与标题大小写正确错误使用有序的标题层级为内容提供有意义的提纲除非绝对必要不要使用 46 级标题标题使用 sentence case如Extend the catalog model标题使用 Title Case如Extend The Catalog Model用井号#表示标题用下划线---或表示标题段落尽量保持段落不超过 6 个句子避免大段无断落的文字墙。需要水平分割线时使用三个连字符---但不要把它当作装饰。链接正确错误使用描述性文字写超链接如 See Getting Started for details.使用含义模糊的链接文字如 See here for details.写 Markdown 风格链接[link text](https://link.gitcode.com/i/28ffea7b4ae15ef3df35390a80c2d30d)写 HTML 风格链接或创建新标签页打开的链接给裸地址加标记https://example.com直接粘贴裸地址https://example.com描述性链接文字尤为重要使用屏幕阅读器的用户常常通过逐条列出链接来浏览页面the Kubernetes configuration能告诉他们链接去向而裸地址做不到。当想直接展示地址本身时语法取决于文件扩展名在.md文件中可以用尖括号或 Markdown 链接。在.mdx文件中必须用 Markdown 链接——尖括号在.mdx中不合法会导致构建失败。仓库对链接的自动化校验也印证了这些约定脚本 scripts/verify-links.js 会遍历仓库中的 Markdown提取所有标题锚点extractHeadingAnchors并处理重复标题的-1、-2后缀以校验页内锚点同时用INVISIBLE_CHAR_PATTERN拦截 URL 中的零宽字符等不可见 Unicode 字符见 verify-links.js#L27-L90。列表如果列表中有任何一项是完整句子则每项都以句号结尾为保证一致性要么全部是完整句子要么全部不是。有序列表统一使用数字1.。无序列表使用-。每个列表后留一个空行。嵌套列表缩进两个空格。步骤序列使用编号列表而不是用 First、Then、Finally 的散文式叙述——编号列表更易扫读、顺序更明确也方便读者指代具体步骤正确错误1) Install the package. 2) Run the migration. 3) Start the server.First, install the package. Then, run the migration. Finally, start the server.表格使用带清晰列头的 Markdown 表格保持内容简洁。对于大量结构化数据考虑改用列表或拆分独立小节而不是塞进一张巨型表格。内容最佳实践首次出现时拼写缩写首次使用缩写时先写出全称并在括号中给出缩写之后可以单独使用缩写正确错误Software Development Kit (SDK)SDK (without ever defining it)Role-Based Access Control (RBAC) ... configure RBAC ...RBAC ... configure RBAC ...Hyper Text Markup Language (HTML)HTML (on first use without expansion)例外URL、API、HTML 这类目标读者软件开发者普遍熟知的缩写无需拼写全称。使用现在时正确错误This command starts a proxy.This command will start a proxy.The plugin provides a catalog page.The plugin will provide a catalog page.例外当必须表达正确含义时才使用将来时或过去时。使用主动语态正确错误You can explore the API using a browser.The API can be explored using a browser.The YAML file specifies the base URL.The base URL is specified in the YAML file.例外如果主动语态会导致表达笨拙可以使用被动语态。使用简单直接的语言正确错误To create a plugin, ...In order to create a plugin, ...See the configuration file.Please see the configuration file.View the catalog entities.With this next command, well view the catalog entities.以 you 称呼读者正确错误You can create a plugin by ...Well create a plugin by ...In the preceding output, you can see ...In the preceding output, we can see ...避免拉丁短语优先使用英文表达替代拉丁缩写正确错误For example, ...e.g., ...That is, ...i.e., ...例外表示等等时可使用 etc.。应避免的写作模式审慎使用 wewe 在教程和引导式文章中是可接受的此时它表示你和我一起完成这个过程。但当它指代不明是 Backstage 项目、维护者还是读者团队时应避免可以避免Next, we need to add the backend package.We provide a new feature ...We can verify this by runningyarn start.In version 1.25, we have added ...避免行话和习语部分读者以英语为第二语言避免行话和习语有助于他们理解正确错误Internally, ...Under the hood, ...Create a new plugin.Spin up a new plugin.避免关于未来的声明不做关于未来的承诺或暗示。如果必须谈论实验性功能请明确标注它是实验性的。避免很快过时的声明避免使用 currently、new 这类时效性强的词——今天的新功能几个月后可能就不再新了正确错误In version 1.25, ...In the current version, ...The search feature provides ...The new search feature provides ...避免假定读者理解程度的词避免 just、simply、easy、easily、simple 这类不增加价值的词正确错误Include one command in ...Include just one command in ...Run the container ...Simply run the container ...You can remove ...You can easily remove ...These steps ...These simple steps ...Backstage 专用词汇表以下术语在全站必须保持一致用法术语用法Backstage始终大写。plugin指概念时小写指具体包时用代码样式例如backstage/plugin-catalog。Software Catalog作为产品名时大写泛指概念时用小写 catalog。Software Templates作为产品名时大写。TechDocs一个单词驼峰式。Scaffolder作为产品名时大写。app-config使用代码样式app-config.yaml。open source两个单词小写句首除外。backend system指 Backstage 后端框架时小写。通用词汇表术语用法GitHub文档中使用 GitHub代码中使用github小写。此外仓库还提供了词汇表条目的专门写作规范 docs/references/writing-a-glossary-entry.md说明词条由标题术语 消歧符、首句定义、可选的补充句与外部链接组成例如用{word} ({disambiguator})的标题形式区分不同语境下的同名术语——这可以视为本风格指南在术语一致性上的延伸落地。规范的工具化落地文档质量如何被自动检查风格指南不只是纸面约定Backstage 用一套脚本将其落地为 CI 可执行的检查Vale 语言检查scripts/check-docs-quality.js 调用 Vale linter配置文件为根目录的 .vale.ini其中StylesPath .github/vale、Vocab Backstage文档库即来自本风格指南中的词汇表。脚本runVale会以--config指定配置并逐文件运行check-docs-quality.js#L83-L103ciCheck则在 CI 中只对 PR 改动的.md文件执行检查并把 Vale 输出转成 GitHub Actions 注解与 eslint 风格的行内报告check-docs-quality.js#L105-L129。需要新增专业词汇时把词加入.github/vale/config/vocabularies/Backstage/accept.txt即可这一点在 CONTRIBUTING.md 的 Vale 说明中也有提及。链接验证scripts/verify-links.js 负责扫描 Markdown 链接验证目标文件与标题锚点是否存在自动处理{#custom-id}显式锚点和 GitHub/Docusaurus 兼容的 slug 化规则并拦截 URL 中的不可见 Unicode 字符防止出现看起来正常但点击失效的链接。本地执行入口在 CONTRIBUTING.md 的文档贡献部分L126、L199明确给出了本地命令yarn run lint:docs即yarn lint:docs # Lint all the Markdown files它运行上述文档质量检查。注意 Vale 需要单独安装并保证全局命令可访问。对于想要为 Backstage 提交文档的开发者推荐的工作流是先在本地运行yarn lint:docs通过 Vale 与链接检查再对照本指南逐项自查格式与措辞若 Vale 对某个代码引用报错用反引号包住该引用即可若是需要认可的专业术语则提交到 accept.txt 词汇表。小结Backstage 文档风格指南的核心可以浓缩为三句话用准确、简洁、友好的英文写作把一切代码与命令相关的内容用反引号标注让自动化工具Vale 与链接检查替你守住格式底线。从语言语气到格式细节再到词汇表和工具链这套规范既保证了百万级文档站点docs 目录 Docusaurus 渲染的一致性也让每一位贡献者的改动都能被快速审查和合并。无论你是贡献 Backstage 文档还是为自己所在团队搭建文档规范这份指南都值得直接借鉴。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考