企业官网建设流程全解析

Prowler 文档品牌语音与技术写作风格体系全解：从 Unbiased Communication 到 MDX 组件规范

【免费下载链接】prowlerProwler is the world’s most widely used open-source cloud security platform that automates security and compliance across any cloud environment.项目地址: https://gitcode.com/GitHub_Trending/pr/prowler

docs/AGENTS.md 是 Prowler 文档体系中的"风格宪法"——一份面向文档作者与 AI Agent 的品牌语音（Brand Voice）和写作规范指南。本篇以该文档为骨架，逐章拆解 Prowler 如何把"去偏见沟通、产品命名纪律、动词化表达、Title Case 标题、MDX 组件约定"落实为一套可执行的规则，并结合仓库中真实存在的 MDX 组件源码与样式实现，说明这些规范在 Prowler 文档站点中是如何落地生效的。读完本篇，你将掌握一套可直接复用于任何开源项目的技术文档风格治理方法，以及 Prowler 文档中版本徽章、适用范围横幅、订阅标记三类组件的完整使用规范。

文档定位：为人与 AI Agent 共同服务的写作规范

文档开头的第一句话就点明了它的受众与使命：

Always that you are writting documentation try to follow this text/communication style guide.

也就是说，凡是撰写 Prowler 文档的场景，都应当遵循这份风格指南。从仓库结构看，这份文档在 Prowler 的文档开发者指南中被明确引用——docs/developer-guide/documentation.mdx 指出 AGENTS.md 文件"包含 Prowler 文档中 AI Agent 的指南与风格指南"。这意味着它同时服务两类读者：人类文档作者，以及参与文档编写的 AI 助手。配套的 skills/prowler-docs/SKILL.md 则以精简形式复述了其中关键规则（品牌语音、格式标准、SEO 优化、MDX 组件），供 Agent 按需调用。

文档的核心立场是 Prowler 的品牌语音定义：Prowler 是一个开源云平台，帮助组织自动化安全监控与合规，覆盖 AWS、Azure、GCP、Kubernetes 和 Microsoft 365 环境。文档要求"这些价值观必须在所有对话与沟通中体现"。下面逐节展开。

无偏见沟通（Unbiased Communication）

Prowler 的目标是触达全球每一位用户，因此其沟通内容必须尽可能包容和多元。文档给出了六组具体原则，这部分是整份规范中可执行性最强的部分。

避免性别化代词

• 尽可能避免使用性别化代词（she/her/hers、he/his/his）；
• 沟通中优先使用第二人称（you/your/yours）；
• 需要用第三人称时改用角色指称（the customer、the user）而非性别代词；
• 若必须使用性别代词，使用 they/them/theirs；
• 禁止 "she/he"、"s/he" 这类双重指称写法。

使用性别中性名词替代

文档给出了一张对照表，把含性别成分的名词替换为中性表达：

多样性、公平与包容

所有沟通必须优先考虑多样性和包容性。举例时需覆盖性别、年龄、身份、种族、文化、背景、能力与 socioeconomic 背景，追求均衡且尊重的呈现。

文化与地理意识

在提及地区、国家、文化、国家地位、政治地位或社会经济现实之前，应做充分调研，保持尊重、知情的态度，避免不必要的冲突。

避免笼统概括

不要对性别、种族、性取向、国籍或文化做宽泛假设。文档给出了一条反面示例："Cybersecurity is of the utmost importance in the country, where corruption runs amok."——这类以偏概全的表述会引入偏见和失实描述。

尊重性语言与清晰可及的语言

• 禁用贬义词；对术语拿不准时，应咨询相关地区或社区的人士确认准确性与得体性；
• 术语（Jargon）：仅当受众预期能理解时才使用技术术语，拿不准时优先选择清晰、普适的语言；
• 俚语（Slang）：即便确信受众能懂，也尽量减少俚语，优先正式、中性的表达。

军事化语言的替代方案

这是安全行业文档写作中很有特色的一条：在网络安全这样敏感的领域，应尽量避免暴力和军事化隐喻。文档给出一张替换表：

"Safety" 与 "Security" 的区分

文档特别澄清了一对常被混淆的词："Safety" 是微观的、个人层面的词，而 "Security" 是宏观的、更宽泛（乃至国家层面）的词。两个例子：

• a. Seat belts are great for personal safety.（安全带关乎个人安全）
• b. National security is of the utmost concern nowadays.（国家安全是当务之急）

在撰写 Prowler 这类安全产品的文档时，混用这两个词会造成语义漂移，这条规则保证了用词精准。

命名规范（Naming Conventions）：产品名的纪律

这一节是整份文档中最"硬"的约束——产品与特性名称被视为专有名词，写作时必须精确使用。

产品家族的精确命名

Prowler 有两条产品线，必须严格使用以下名称：

Prowler Products（商业产品）：

• Prowler Cloud
• Prowler Private Cloud（原 Prowler Enterprise）
• Prowler Hub
• Prowler Lighthouse AI
• Prowler MCP

Open Source projects（开源项目）：

• Prowler CLI
• Prowler Local Server（原 Prowler App）
• Prowler Local Dashboard（Prowler CLI 的仪表盘）
• Prowler SDK

规范明确禁止在新文档中出现旧名 Prowler App 与 Prowler Enterprise。唯一允许出现旧名映射的位置有两处：Prowler Product Families 页面（docs/getting-started/products/index.mdx）和全站横幅，这两处专门负责记录新旧名称的映射关系。仓库中的产品家族页面确实维护了一张 "Former Names" 表（Prowler App → Prowler Local Server，Prowler Enterprise → Prowler Private Cloud），与 AGENTS.md 的规定一一对应。

其他 Prowler Features 的规范写法

文档同时把一批功能名也列为专有名词，要求不带冠词引用，包括：Built-in Compliance Checks、Multi-cloud Security Scanning、Autonomous Cloud Security Analyst (AI)、Threat & Misconfiguration Detection、Role-Based Access Control (RBAC)、Identity & Access Risk Detection、Tag-Based Scanning & Filtering、Audit Logs & Security Reports、Agentless & Works Anywhere、Automated Scans & Continuous Monitoring、Chat-based Security Querying (AI)、AI-Generated Detections & Remediations、Prowler Studio、Custom Security Policies、Open Source & Full APIs。

动词化表达（Verbal Constructions）

文档主张"能用动词结构就不用名词结构"，理由有三点：

• 清晰度：名词化结构往往引入不必要的复杂性或含糊；
• 简洁性：动词结构通常用词更少；
• 可读性：表达更精炼。

对比示例：

文档还附了一个补充条款（Addendum）：动词结构能"说出你的目的"。例如 "Recommendation for multiple subscriptions"（含糊、甚至有歧义）应改为 "Recommendation for Managing Multiple Subscriptions"——动词 "Managing" 明确了目的。规则是：动词能表达目的时，必须使用动词。

第二人称的使用纪律

文档提出了一条看似矛盾、实则自洽的规则：在"无偏见沟通"章节要求优先用第二人称，但在全局层面又要求"尽可能少用 you/your"，仅保留用于祈使句式的直接指令。

改进示例：

• Original:"Prowler Local Server can be installed in different ways, depending on your environment:"
• Improved:"Prowler Local Server offers flexible installation methods tailored to various environments:"

也就是说，叙述性内容中隐去 "你"，只有在给读者下达明确操作指令时才允许出现第二人称。这条规则显著降低了文档的口语感，也让行文更聚焦于产品本身。

大小写规则（Capitalization）

Title Case

标题一律使用 Title Case，例如 "This Is an Example on Title Case"。文档给出的理由偏向 SEO：Title Case 提升可读性、让标题在视觉上更突出，从而提高点击率（CTR）。

其他大小写细则

• 内部大小写（Inner Capitalization）：正文中避免单词内部的大写，除非是专有名词或品牌名。例如用 email/e-mail 而非 E-mail，用 e-book 而非 e-Book；
• 缩写词：缩写的全称不逐词大写——写 "CTI (cyber threat intelligence)" 而非 "CTI (Cyber Threat Intelligence)"；但像 "AWS (Amazon Web Services)" 这类本身按词首大写的名称保持原样；
• 禁止用大写表强调：不要用全大写单词来强调语气；
• 语言与标准的写法：HTML、JSON、YAML、XML 等必须大写；标准名遵循 Title Case，如 Industrial Automation and Control Systems (IACS)；
• 法律与法规：遵循 Title Case；引用非本国法律时加上国别和原名。文档示例：Code for the Cybersecurity Law published in the Spanish Official State Bulletin (BOE, Boletín Oficial del Estado)；欧盟法规应到官方翻译门户核对各语言版本并选用合适语言。

连字符（Hyphenation）及其 SEO 含义

• 前置名词修饰语必须连字符：如 "a world-leading company in open-source software"；
• 后置表语形容词不加连字符：如 "Prowler has many features built in."

文档还解释了连字符与 SEO 的关系：Google 把连字符当作与空格等同的词分隔符，即high quality checks与high-quality checks被同等看待——因此连字符不影响正文 SEO，按语法规正确写法即可。但下划线_会被当作不同的词，这对 URL 有实际影响：

• 更好：example.com/this-is-an-URL
• 欠佳：example.com/this_is_an_URL

结论是 URL 中优先使用连字符，既提升可读性也有利于索引。

项目符号（Bullet Points）的写作约定

为什么要用项目符号

文档列出五点理由：信息可扫读（垂直阅读）、突出要点、提升记忆保持、结构化呈现，以及 SEO 收益（降低跳出率、增加停留时间、便于关键词优化、提升被搜索摘要收录的概率、增强可爬取性）。

何时使用

• 信息可被逻辑地划分为多个类别，且各类别共享某些特征或分类属性；
• 每个条目本身足以作为独立概念单独成条。

文档给出了一个完整改造案例：把一段罗列合规框架的长句改写为分类清单。原文是 "It contains hundreds of controls covering CIS, NIST 800, NIST CSF, CISA, RBI, FedRAMS, PCI-DSS, GDPR, HIPAA, FFIEC, SOC2, GXP, AWS Well-Architected Framework Security Pillar, ..."；改写后按类别分条并加粗类别名：

• Industry standards:CIS, NIST 800, NIST CSF, and CISA
• Regulatory compliance and governance:RBI, FedRAMP, and PCI-DSS
• Frameworks for sensitive data and privacy:GDPR, HIPAA, and FFIEC
• Frameworks for organizational governance and quality control:SOC2 and GXP
• AWS-specific guidance:AWS Foundational Technical Review (FTR) and AWS Well-Architected Framework (Security Pillar)
• Regional compliance:ENS (Spanish National Security Scheme)
• Custom security frameworks:Tailored to meet the organization's specific needs

项目符号的标点三选一

• 不加标点（极简式）：适用于没有动词的条目，适合孤立地罗列产品或特性。例如 "Prowler Local Server is composed of three key components:" 下面列 Prowler UI / Prowler API / Prowler SDK，"以无噪点的方式突出每个元素"；
• 完整句子加句号：每个条目构成完整句子或含动词时使用。例如给三个组件各写一句带定语的完整描述；
• 分号 + 末句句号：传统上用于条目构成连续句子的场景，但文档明确该方式"正在被弃用"（与分号在现代写作中减少使用一致），应尽可能避免。

无论选哪种风格，全文必须保持一致。

给项目符号加小标题

技术写作中，给每条 bullet 加一个加粗小标题是"强有力的技巧"：提升清晰度与可用性，同时带来 SEO 收益（可爬取性、关键词整合、用户参与度、被搜索引擎收录为摘要的机会、降低跳出率）。文档的建议是"尽可能给 bullet 加标题"——上面合规框架示例正是这一技巧的示范。

引号（Quotation Marks）使用规范

文档遵循美式英语约定，区分双引号与单引号：

双引号

• 用于书名、电影、歌曲、文章标题；
• 包裹直接引语，整句引用时首字母大写，句中短语引用不大写；
• 反讽含义时用 "scare quotes"：The update is "scheduled" to release next week.
• 引用一个词本身而不赋予其含义时用双引号（或斜体）。

单引号

• 用于双引号内部；英式英语中顺序通常相反（单引号在外）。

软件文档中的双引号细则

这一小节直接指导 Prowler 用户指南的写作：

1. 菜单项与 UI 选项：引用可点击的界面元素时用双引号——Click "File" and select "Save As";
2. 按钮与命令：用户交互的带标签界面元素用双引号——Select "Submit" to finalize the form.
3. 精确输入：需要用户逐字输入的内容用双引号——Type "admin" in the username field.
4. 软件名称不加引号：软件产品名不加引号（除非为了消歧）。正确：Open Microsoft Excel.；错误：Open "Microsoft Excel."

交互动词（Interaction Verbs）

文档为"用户与软件交互"的动作定义了一套必须使用的标准动词，按平台分三类：

鼠标与触控板（桌面/笔记本）

触屏操作（移动设备）

其他动作

• Drag：按住并移动——Drag the file into the folder.
• Swipe：手指在屏幕上水平或垂直滑动——Swipe left to dismiss the notification.
• Pinch to zoom：双指缩放——Pinch the screen to zoom in on the image.
• Scroll：滚轮、滑动或方向键上下移动——Scroll down to see more results.

文档并注明：手势术语的"广泛接受的定义"以 Windows 官方文档为准。

句子结构与 SEO：先说目的，再说动作

文档用 Prowler 自身文档中的两种句式做了对比：

• Option 1:"Open a terminal and execute the following command to create a new custom role."
• Option 2:"To create a new custom role, open a terminal and execute the following command."

分析结论：

• SEO 角度：搜索引擎优先识别句首的明确意图。Option 2 以用户最可能搜索的动作（"Create a custom role"）开头，更易匹配搜索查询；Option 1 把关键搜索词放在句尾，关键词优化效果差；
• 技术写作角度：先目标、后动作。Option 1 在分步指南中仍可接受，但 Option 2 对教程、手册和文档更有效。

文档给出的心法：

• 用"最可能找到该信息的用户的写法"来起草内容（即 "Ctrl + F approach"——想象读者会在页面里搜什么词）；
• 把关键词与关键术语放在句首；
• 经验法则："In order to what"（目的）先于 "what"（动作），且 "what" 必须镜像用户最可能的搜索写法。

章节标题与 Header 规范

Header 的四大功能

改进导航（快速定位）、增强可读性（把复杂主题切分为可管理的小节）、建立层级（定义内容逻辑流）、以及 SEO（搜索引擎用标题判断内容层级与相关性：H1 唯一且有描述性，H2–H6 逻辑地拆分内容）。SEO 友好的标题实践：自然包含关键词、避免关键词堆砌、使用 H1 → H2 → H3 的结构化层级。

Header 层级约定

• Title：文档主标题（H1）
• Main Sections：一级标题（H2）引入关键内容区
• Subsections：二级标题（H3）细化具体主题
• Subtopics：H4 及更深层级，少量用于更细的颗粒度

文档还给出 Markdown 层级示意（H1 文档标题 → H2 主节 → H3 小节 → H4 子主题）。

撰写有效标题的准则

• 要有描述性：避免 "Introduction"（太含糊），应写 "Introduction to AWS CloudShell Installation"；
• 简洁：不用多余的词；
• 一致：全文统一格式与风格；
• 避免特殊字符：克制使用标点，避免过多符号、破折号或下划线；
• Title Case：好——"How to Clone and Install Prowler from GitHub"；差——全小写版本。技术文档中子标题可用 Sentence Case 提升可读性，但这只是建议且必须全文一致（例如 header 用 "How to install uv dependencies" 的 Sentence Case）；
• 标题包含关键词：好——"Scanning AWS Accounts in Parallel"；差——"Ways to scan on AWS"（含糊且不精确）；
• 跨文档一致性：常见章节用统一措辞（如 "Installation"、"Setup"、"Configuration"），结构化指南中按需编号（如 "Step 1: Install Prowler"）。

MDX 组件规范：Version Badge、AppliesTo 横幅与 Cloud Marker

文档的后半部分从"语言规则"转向"组件规则"，规定了三类文档组件的使用方式。这三者在仓库中都有真实实现，是"规范驱动文档工程化"的典型样本。

Version Badge（版本徽章）

用途：标明某功能是在 Prowler 的哪个版本引入的。适用场景：某版本新增的功能、新的 CLI 选项或 flag、新的 API 端点或 SDK 方法、新的合规框架或安全检查、破坏性变更或已弃用功能（需附上下文）。

使用步骤：

1. 在 MDX 文件顶部导入：import { VersionBadge } from "/snippets/version-badge.mdx"；
2. 把徽章放在小节标题或功能标题正下方：<VersionBadge version="4.5.0" />；
3. 版本号用语义化版本格式（如4.5.0、5.0.0），不带 "v" 前缀。

放置细则：徽章独占一行、紧跟标题下方；徽章后空一行再写正文；子节仅在"独立于父节引入了新东西"时才放徽章。

从源码看，docs/snippets/version-badge.mdx 中该组件接收一个versionprop，渲染为一个指向 GitHub release 页面的链接，内部结构为 "Added in: {version}" 的两段式徽章；其样式（深色渐变胶囊、等宽字体版本号、暗色主题下的绿色变体）定义在 docs/style.css 顶部的 ".version-badge-*" 规则中。也就是说，规范中"语义化版本、不加 v"的约束最终由组件拼接 release 链接的逻辑来兜底——版本号直接参与构造跳转 URL。

AppliesTo 横幅（产品适用范围）

用途：声明一篇指南覆盖哪些产品，并链接到产品家族页面。文档规定：

• 使用时机：用于覆盖多个产品的 Web UI 教程页（例如一篇写自 Prowler Cloud、但步骤同样适用于 Prowler Local Server 的指南）；
• 禁止叠加：不要与 SubscriptionBanner 同时使用——带 SubscriptionBanner 的页面已经声明了自身可用性；
• 用法：import { AppliesTo } from "/snippets/applies-to.mdx"后写<AppliesTo />；
• 默认范围：Prowler Cloud、Prowler Private Cloud、Prowler Local Server；可通过productsprop 收窄，例如<AppliesTo products={["Prowler Cloud", "Prowler Private Cloud"]} />；
• 位置：若页面有 Version Badge，则横幅放在徽章下方单独一行；否则紧跟 import 之后。

仓库中 docs/snippets/applies-to.mdx 的实现与规范完全对应：默认参数即三个产品名的数组，组件渲染为一个 Info 框，把产品名加粗拼成 "This guide applies to …" 的句子（并正确处理 ", and" / " and " 的英文连词），末尾链接到 "Prowler product families" 页面。

Cloud Marker（订阅内容标记）

仓库中的绿色云图标 docs/images/icons/cloud-bold.svg 用于标记需要 Prowler Cloud 或 Prowler Private Cloud 订阅的内容。从 docs/style.css 的实现看，它通过::after伪元素渲染在侧边栏标签尾部，从而保证侧边栏文字保持左对齐；文档对它的维护规则极为具体：

• 页面级：每个订阅门控页面都要在 Cloud marker 规则中加一条li[id="<页面路径>"] a span::after选择器，li的 id 等于页面 URL 路径；若页面只有单个小节被门控（例如 Support 页只有 Support Desk 带 SubscriptionBanner），则不加标记。样式表中确实列出了一批li[id="/user-guide/tutorials/..."]选择器，与这条规则一一对应；
• 导航组级：仅当组内所有页面都被门控时才加选择器。文档列出了唯一被批准的例外——Prowler MCP 组：托管在mcp.prowler.com的服务器包含 Prowler Cloud 专属功能工具，而其概览页说明了免费的本地替代方案。嵌套组渲染为li[data-title="<组名>"]加按钮切换，选择器写作li[data-title="<组名>"] > button span:first-child::after；顶层组渲染为不带data-title的h3标题，因此与嵌套组同名冲突会自然消解；门控的顶层组（始终展开）通过:has()选中其兄弟列表（如 Security 标签组）。文档特别警告：不要在嵌套组的子链接上用:has()——折叠的组不渲染其子节点；
• 禁用项：不要为此标记使用导航的icon字段（图标渲染在标签前会导致侧边栏错位）；也不要给导航组用"tag"字段——组级 tag 会导致构建工具 mint 的 broken-links 检查栈溢出崩溃（文档注明该结论在 mint 4.2.689 版本上验证过）；
• 颜色固定：SVG 笔画刻意使用固定品牌绿#10B981，因为它必须在明暗两种主题下都可见，不能依赖currentColor；
• 语义说明：标记含义的说明文字维护在产品家族页面（docs/getting-started/products/index.mdx），该说明必须保留在原位。

style.css 中同样有一段配套说明：侧边栏宽度被加宽 2rem（默认 18rem → 20rem），让带云标记的门控标签能在一行内放下，内容列的偏移量随之联动调整。

不预设读者专业水平（Avoid Assumptions Regarding Audience's Expertise）

文档要求即使了解目标受众，也不得假设其专业知识，并给出若干具体做法：

• 首次出现时定义关键术语与缩写：即便受众是技术人员，领域术语也可能各不相同。行话先定义再使用；缩写首次出现必须展开，如 AWS Identity and Access Management (IAM)、Multifactor Authentication (MFA)；
• 不要假设未写明的知识：即便资深读者也可能不知道某些前置条件。如果流程依赖之前的步骤，应简要指回，例如 "Before configuring security groups, ensure VPC networking is set up."；
• 提供尽可能多的示例（"Provide as Many Examples as Deemed Right… and Then Some"）；
• 预判常见知识缺口；
• 控制 Note 的使用：Notes 经常被读者跳过且会污染正文，只用于"非必需但附加"的信息，或会引发错误/失误的提示。

Warnings 与 Danger Calls：高严重度信息的表达

技术文档中，Warning 与 Danger 用于突出关键风险，引导用户避免安全事件或系统故障。文档给出三要素：

1. 定义严重级别：
   • Note：一般信息或最佳实践（低严重度）
   • Warning：不遵循操作指引可能导致潜在问题（中严重度）
   • Danger：可能带来严重后果（如系统损坏或数据丢失）的操作（高严重度）
2. 说明后果：每个 Warning/Danger 必须显式描述忽视该警告的影响。好例子："Disabling encryption may expose sensitive data to unauthorized access."；差例子："Avoid disabling encryption."（只说避免，不说后果）
3. 提供补救与排障路径：尽可能把用户引向排障指南或缓解步骤。示例：**Danger:** Running this command will **permanently delete all data**. Refer to @Data Recovery Guide for restoration steps.

skills/prowler-docs/SKILL.md 中对应的 MDX 写法即<Warning>与<Danger>组件包裹上述文本。

小结：这份风格指南的三层结构

通读 docs/AGENTS.md 可以把它归纳为三个层次，这也是它值得作为"文档治理"范本的原因：

• 语言层：去偏见沟通、动词化表达、第二人称纪律、大小写、连字符、引号、交互动词、句子结构——解决"怎么说"的问题，且每条规则都配了正/反例对照，可直接执行；
• 术语层：产品家族名、旧名映射、功能专有名词——解决"叫什么"的问题，并与 docs/getting-started/products/index.mdx 的产品名登记表形成双写一致；
• 工程层：Version Badge、AppliesTo 横幅、Cloud Marker——解决"怎么标"的问题，每一条规则都能在 docs/snippets/version-badge.mdx、docs/snippets/applies-to.mdx 和 docs/style.css 中找到对应的真实实现。

对贡献者而言，这套规范的价值在于：它把"品牌语音"从一句空泛的口号拆解成了可审查、可自动化核对、可被 AI Agent 直接消费的规则集，使得 Prowler 文档站中数百篇指南在语气、命名和结构上保持了一致性。

【免费下载链接】prowlerProwler is the world’s most widely used open-source cloud security platform that automates security and compliance across any cloud environment.项目地址: https://gitcode.com/GitHub_Trending/pr/prowler