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

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/prowlerdocs/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 CommunicationProwler 的目标是触达全球每一位用户因此其沟通内容必须尽可能包容和多元。文档给出了六组具体原则这部分是整份规范中可执行性最强的部分。避免性别化代词尽可能避免使用性别化代词she/her/hers、he/his/his沟通中优先使用第二人称you/your/yours需要用第三人称时改用角色指称the customer、the user而非性别代词若必须使用性别代词使用 they/them/theirs禁止 she/he、s/he 这类双重指称写法。使用性别中性名词替代文档给出了一张对照表把含性别成分的名词替换为中性表达原词推荐替代BusinessmanEntrepreneur, businessperson, executiveSalesmanSales executive, sales representativeMankindHumanity, peoplePenmanshipCalligraphy, handwritingMiddlemanIntermediary, negotiator多样性、公平与包容所有沟通必须优先考虑多样性和包容性。举例时需覆盖性别、年龄、身份、种族、文化、背景、能力与 socioeconomic 背景追求均衡且尊重的呈现。文化与地理意识在提及地区、国家、文化、国家地位、政治地位或社会经济现实之前应做充分调研保持尊重、知情的态度避免不必要的冲突。避免笼统概括不要对性别、种族、性取向、国籍或文化做宽泛假设。文档给出了一条反面示例Cybersecurity is of the utmost importance in the country, where corruption runs amok.——这类以偏概全的表述会引入偏见和失实描述。尊重性语言与清晰可及的语言禁用贬义词对术语拿不准时应咨询相关地区或社区的人士确认准确性与得体性术语Jargon仅当受众预期能理解时才使用技术术语拿不准时优先选择清晰、普适的语言俚语Slang即便确信受众能懂也尽量减少俚语优先正式、中性的表达。军事化语言的替代方案这是安全行业文档写作中很有特色的一条在网络安全这样敏感的领域应尽量避免暴力和军事化隐喻。文档给出一张替换表军事化表述推荐替代Combat, fight, eliminateAddress, protect, safeguard, wardKill chainCyberattack chainAttackerCyberattacker, bad actor, threat actorDefense-in-depth approachMultilayered approachFirst line of defense, frontlineSecurity, protection, defenseExternal attack surfaceVulnerabilities, point of access, external exposureSafety 与 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 CloudProwler Private Cloud原 Prowler EnterpriseProwler HubProwler Lighthouse AIProwler MCPOpen Source projects开源项目Prowler CLIProwler Local Server原 Prowler AppProwler Local DashboardProwler CLI 的仪表盘Prowler SDK规范明确禁止在新文档中出现旧名 Prowler App 与 Prowler Enterprise。唯一允许出现旧名映射的位置有两处Prowler Product Families 页面docs/getting-started/products/index.mdx和全站横幅这两处专门负责记录新旧名称的映射关系。仓库中的产品家族页面确实维护了一张 Former Names 表Prowler App → Prowler Local ServerProwler 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文档主张能用动词结构就不用名词结构理由有三点清晰度名词化结构往往引入不必要的复杂性或含糊简洁性动词结构通常用词更少可读性表达更精炼。对比示例名词化避免动词化推荐The creation of the report was successful.The report was successfully created.The implementation of the solution reduced system downtime.The solution reduced system downtime.文档还附了一个补充条款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:也就是说叙述性内容中隐去 你只有在给读者下达明确操作指令时才允许出现第二人称。这条规则显著降低了文档的口语感也让行文更聚焦于产品本身。大小写规则CapitalizationTitle Case标题一律使用 Title Case例如 This Is an Example on Title Case。文档给出的理由偏向 SEOTitle 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 CISARegulatory compliance and governance:RBI, FedRAMP, and PCI-DSSFrameworks for sensitive data and privacy:GDPR, HIPAA, and FFIECFrameworks for organizational governance and quality control:SOC2 and GXPAWS-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 organizations specific needs项目符号的标点三选一不加标点极简式适用于没有动词的条目适合孤立地罗列产品或特性。例如 Prowler Local Server is composed of three key components: 下面列 Prowler UI / Prowler API / Prowler SDK以无噪点的方式突出每个元素完整句子加句号每个条目构成完整句子或含动词时使用。例如给三个组件各写一句带定语的完整描述分号 末句句号传统上用于条目构成连续句子的场景但文档明确该方式正在被弃用与分号在现代写作中减少使用一致应尽可能避免。无论选哪种风格全文必须保持一致。给项目符号加小标题技术写作中给每条 bullet 加一个加粗小标题是强有力的技巧提升清晰度与可用性同时带来 SEO 收益可爬取性、关键词整合、用户参与度、被搜索引擎收录为摘要的机会、降低跳出率。文档的建议是尽可能给 bullet 加标题——上面合规框架示例正是这一技巧的示范。引号Quotation Marks使用规范文档遵循美式英语约定区分双引号与单引号双引号用于书名、电影、歌曲、文章标题包裹直接引语整句引用时首字母大写句中短语引用不大写反讽含义时用 scare quotesThe update is scheduled to release next week.引用一个词本身而不赋予其含义时用双引号或斜体。单引号用于双引号内部英式英语中顺序通常相反单引号在外。软件文档中的双引号细则这一小节直接指导 Prowler 用户指南的写作菜单项与 UI 选项引用可点击的界面元素时用双引号——Click File and select Save As;按钮与命令用户交互的带标签界面元素用双引号——Select Submit to finalize the form.精确输入需要用户逐字输入的内容用双引号——Type admin in the username field.软件名称不加引号软件产品名不加引号除非为了消歧。正确Open Microsoft Excel.错误Open Microsoft Excel.交互动词Interaction Verbs文档为用户与软件交互的动作定义了一套必须使用的标准动词按平台分三类鼠标与触控板桌面/笔记本动词定义示例Click按下并释放左键或触控板不移动指针及物动词Click the OK button to confirm.Click on与 Click 常可互换但技术写作中较少推荐Click on the Settings icon.不推荐优先 ClickDouble-click快速双击通常用于打开文件或应用Double-click the document to open it.Right-click右键打开上下文菜单Right-click the folder and select Properties.触屏操作移动设备动词定义示例Tap轻触屏幕等价于鼠标的 ClickTap the Sign in button.Double-tap快速触摸两次常用于缩放或选中文本Double-tap an image to zoom in.Press and hold按住不放以访问更多选项类似桌面 Right-clickPress and hold an app icon to see more actions.其他动作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文档主标题H1Main Sections一级标题H2引入关键内容区Subsections二级标题H3细化具体主题SubtopicsH4 及更深层级少量用于更细的颗粒度文档还给出 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 方法、新的合规框架或安全检查、破坏性变更或已弃用功能需附上下文。使用步骤在 MDX 文件顶部导入import { VersionBadge } from /snippets/version-badge.mdx把徽章放在小节标题或功能标题正下方VersionBadge version4.5.0 /版本号用语义化版本格式如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 Audiences 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 用于突出关键风险引导用户避免安全事件或系统故障。文档给出三要素定义严重级别Note一般信息或最佳实践低严重度Warning不遵循操作指引可能导致潜在问题中严重度Danger可能带来严重后果如系统损坏或数据丢失的操作高严重度说明后果每个 Warning/Danger 必须显式描述忽视该警告的影响。好例子Disabling encryption may expose sensitive data to unauthorized access.差例子Avoid disabling encryption.只说避免不说后果提供补救与排障路径尽可能把用户引向排障指南或缓解步骤。示例**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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考