风格指南

本风格指南适用于任何非核心文档团队成员。使用此文档作为关于适当词语选择的入门指南。

除了这里提到的指南之外，如果您感到困惑，请参考Google 风格指南以做出任何决定。

语气和语调

  • 使用主动语态。把它想象成你在指导用户。
  • 使用现在时态。学习者可能正在浏览我们要求他们执行的实施示例和文件夹。
  • 谨慎使用将来时态，仅用于指示结果。
    • 使用：当您发送请求时，响应将包含以下信息。
    • 避免：将出现新窗口。
  • 写简短、简洁的句子。如果您在说写下的整个句子时需要喘口气，请将其分成两句话。

标题

  • 避免使用动名词来描述过程主题

    • 使用：选择一个自动化引擎
    • 避免：选择自动化引擎

  • 使用句子大小写来表示标题

    • 使用：选择一个自动化引擎
    • 避免：选择一个自动化引擎

  • 使用不以 -ing 动词开头的名词短语。

    • 使用：Nightwatch API 概述
    • 避免：了解 Nightwatch API

文本格式

  • 避免过度使用粗体。仅在将 UI 元素用作操作时将其应用于粗体。
    • 使用：点击Automate 仪表板上的访问密钥。
    • 避免：您可以在Automate 仪表板上获取您的 BrowserStack 访问密钥。
  • 不要使用斜体。
  • 避免使用下划线。
  • 对所有句子使用句子大小写。除了产品名称、行业术语或 BrowserStack 特定的功能/关键字之外，不要将任何单词大写。
    • 使用：Python、本地测试、Chrome
    • 避免：会话 ID、日志、桌面、身份验证
  • 谨慎使用行话。尽可能使用更简单的词语。
    • 避免使用括号() 来表示可选信息。例如，
    • 避免：Hub 在多台机器（节点）上并发执行测试。
    • 使用：Hub 在多台机器或节点上并发执行测试。
  • 使用代码字体来表示文件名、文件路径、内联代码。
  • 使用代码格式表示输入值。例如，在 abc 框中，输入abc。

文件夹/网络导航

  • 文件夹导航
    • 使用：导航到/opt/home目录。
    • 使用：导航到/opt/home目录并打开abc.js文件。
    • 避免：转到/opt/home目录。
  • 网络导航

列表

  • 每个列表都需要一个引导句来解释列表的作用。
  • 对需要按特定顺序执行的过程使用编号列表。
  • 保持并行的句子结构。例如，请参见下文
    • 配置您的 BrowserStack 凭据
    • 将 BrowserStack 测试结果嵌入您的作业结果中
  • 当只有一项时，不要使用项目符号（数字或符号）；必须至少有两项才能构成列表。在这种情况下，将其转换为句子。