Expensify应用帮助文档编写规范详解

Expensify应用帮助文档编写规范详解

前言

在开发Expensify这款超级应用的过程中，我们意识到清晰、一致的帮助文档对于用户体验至关重要。本文档详细阐述了Expensify应用帮助系统的编写规范，旨在为技术文档编写者提供明确的指导原则。

核心设计理念

Expensify帮助文档遵循三大核心理念：

1. 一致性原则：所有页面、章节和部分都遵循统一的模式，确保用户在不同功能间切换时能够快速适应文档结构。

2. 专注性原则：每个部分都专注于一个自包含的主题，复杂主题会被分解为多个小组而非单一冗长的部分。

3. 简明语言原则：所有内容都采用高中阅读水平的语言，使用常见词汇和简单句式，确保各类用户都能轻松理解。

文档层级结构

Expensify帮助系统采用严谨的层级结构：

1. 站点(Site)

整个帮助系统构成一个完整的"站点"，全面覆盖Expensify超级应用的所有功能。

2. 页面(Page)

每个"页面"专注于应用中的一个独立产品模块。虽然可以提及其他模块，但详细说明仅限当前页面主题，避免内容重复。

3. 章节(Chapter)

每个产品页面包含四个标准章节，使用H2标题标记。

4. 部分(Section)

每个章节包含三个或更多"部分"，由标题和正文组成。

标准章节结构

每个帮助页面必须包含以下四个核心章节：

1. 介绍(Introduction)

使用非技术性语言概述产品价值，包含三个固定部分：

• 主要用途：定义列表形式列出产品的关键使用场景
• 核心用户：定义列表形式列出产品的主要目标用户群体
• 关键优势：定义列表形式列出产品相比竞品的主要优势

2. 概念(Concepts)

建立清晰的产品术语体系，包含：

• 三个或更多定义列表部分或部分组
• 仅解释概念本身，不包含操作指南或FAQ内容

3. 教程(Tutorials)

提供详细的操作步骤指南，要求：

• 三个或更多操作指南部分或部分组
• 所有术语使用与概念章节一致的定义
• 每个步骤只描述一个用户操作

4. 常见问题(FAQ)

解答特定疑问，规范包括：

• 三个或更多FAQ部分或部分组
• 不引入新术语(应在概念章节定义)
• 不提供逐步指导(应在教程章节说明)

标题规范

Expensify帮助文档采用两种标题格式：

1. 短标题

• 1-3个简短单词
• 适合左侧导航显示不换行
• 主要单词首字母大写
• 示例：# 平台

2. 长标题

• 4个以上单词
• 以方括号包含的短标题开头
• 提出完整问题，使用标准句子格式
• 示例：# [平台] 我可以在哪些设备上使用Expensify应用？

内容部分类型

1. 定义列表部分

用于分解高级概念，包含：

• 以"What"开头的长标题
• 1-2句介绍性文字
• 无编号项目列表，每项包含：
  • 1-3个加粗术语
  • 1-3句明确定义
• 列表后不添加额外内容

2. 操作指南部分

提供分步操作说明，要求：

• 以"How"开头的长标题
• 1-2句目标说明
• 编号步骤列表，每步包含：
  • 加粗的UI元素名称
  • 操作目的说明
  • 仅描述一个用户动作
• 确保所有步骤共同达成既定目标
• 所有术语已在概念章节定义

3. FAQ部分

解答特定问题，规范包括：

• 以"Why"开头的长标题
• 2-4句完整回答
• 不使用项目列表或编号步骤
• 不回答"How"问题(应放在教程章节)

跨平台编写规范

Expensify作为跨平台应用，文档编写需考虑：

1. 通用动词：优先使用"点击"而非"单击"或"轻触"等平台特定术语

2. 平台差异说明：当操作方式不同时，需同时说明各平台对应操作，如"右键点击或长按打开上下文菜单..."

3. 平台限定说明：对于平台特有功能，需明确标注适用平台，如"如果您使用鼠标，悬停在聊天上可显示悬浮菜单..."

语言风格指南

为确保文档风格统一：

1. 人称使用：

   • "您"指代阅读文档的用户
   • "我们"指代Expensify公司
   • "我们"可替换为"Expensify"而不影响语义

2. 文档定位：帮助文档本质上是产品/公司直接与用户的第一人称对话

3. 语气要求：保持专业但友好的语气，避免过于正式或随意

最佳实践建议

1. 内容测试：编写完成后，应实际按照文档步骤操作验证准确性

2. 用户视角：始终从用户角度出发思考问题表述方式

3. 术语统一：建立并维护术语表，确保全文档术语使用一致

4. 版本控制：文档更新需注明适用的应用版本号

通过遵循这些规范，我们可以确保Expensify帮助文档保持高质量、一致性和易用性，为用户提供最佳的支持体验。