Shoppe的工作主要是给内部开发者提供开发工具或者说开发平台，帮他们使用内部的标准化开发流程，提升开发效率和开发体验。这份工作和我以前的工作经验最大的区别是面对的用户是内部开发者。

面对大量的内部用户，所有问题一一探讨是不可能的。此时文档就是个很重要的交付件，好的文档能减少大量的交互成本。

科技写作并不是我擅长的，所以我在这份工作中也学习了很多。

Gas是一个基于Go的应用开发框架，集成了内部的统一sdk和一些基础服务，比如日志、监控、配置、CICD等。思想类似faas，业务项目的开发者只需要关注业务逻辑，并使用统一的sdk进行开发，后续非业务功能的集成和升级都通过框架来实现。

在基础功能都基本完成后，就需要接入种子用户了。这时就需要文档了。

文档的用户是谁⌗

虽然文档的用户是开发者，但是我们没法保证他们都是非常专业，有些对golang技术栈或者内部的技术栈有些可能都不是很熟悉。所以文档的目标是让用户能够快速上手，而不是让用户能够深入了解。

Learn by example⌗

提供demo是快速上手的有效方式。

  • 从最简单的例子开始，让用户能够快速上手。比如一个最简单的http server，一个最简单的rpc server。 然后就是项目的部署。这样一个完整的流程就有了。

  • 开发过程中有许多细节，都可以编写最简单的用例版本。后续的迭代中填充，比如如何使用日志，如何使用监控，如何使用配置中心，如何使用各种中间件，如何配置CICD等。

在快速发布之后，会收到来自用户的反馈，根据用户的反馈不断完善文档。可以根据反馈问题的影响程度和用户的反馈情况来排定优先级。在开始的阶段，很可能不仅是文档的问题，还有产品的问题，可能需要的修改代码甚至设计。

文档类型⌗

整个项目的文档主要分为以下几类：

  • Getting Started or onboarding
  • Tutorials
  • Reference
  • FAQ

Getting Started⌗

Getting Started是面向新用户的，目的是让用户快速上手体验，而不是让用户深入了解。

在简单的例子中，无法覆盖所有的细节。必要的说明可以简单提及并给出链接让想要深入了解的人可以继续学习。

常常可能出现的提供太多细节，而模糊了焦点；或者例子太过复杂，让用户无法理解，望而却步。

Tutorials⌗

有时候也被称为how-tos或者guides。一般是Getting Started的下一步。

如果你的产品或者项目可以区分模块或者子项目，需要tutorial sections。

Gas除了服务的engine, 还有集成其他基础模块的子项目，如db, mq, cache等。每个子项目都在自己的repo中，都有对应的ic来完成各自的markdown tutorial。通过SSG(Static Site Generator)来整合所有repo的tutorial。

常见的Tutorials的组织方式有两种，一种是按照功能来组织，一种是按照用例。

  • 按照功能： 从内部开发者的视角说明 What something does, 比如config sdk提供哪些功能，如何使用。
  • 按照用例： 从外部用户的视角说明 What someone wants to do with it, 比如服务的不同regions，有不同的配置，该怎么使用config sdk来完成。

除非应用一开始就是为了特定目的构建的，否则我们很可能是不清楚实际的用例的。所以一开始我们可以按照功能来组织tutorials。随着时间的推移，我们会收到足够的用户反馈，然后再添加各种用例场景的tutorial。

务实地说，我们知道要满足所有人的需求几乎是不可能的。大多数人对文档总会有些意见，因为它无法回答每个人具体的问题和用例。这并不是说不应该努力去满足和超越人们的期望——我的观点是，这一切都需要时间。

Reference⌗

该部分包含了技术细节，每个单独的组件，函数、或者API具体都是怎么样的。

它和前面两种类型的文档的区别是

  • getting started或者tutorials告诉你怎样使用
  • reference告诉你使用的各种参数和细节

比如， 在tutorials中你知道怎么使用config sdk，但你无法知道sdk的所有配置参数，这些需要在reference中了解。

不同项目的和技术类型的reference可能包括：

  • SDK function details
  • API endpoint details
  • Architecture and design details
  • Security and privacy details

SDK⌗

我们通常会首先从SDK开始，因为编程语言基本都可以根据注释之类的生成SDK文档。这项工作可以在开发中一起完成。

API⌗

看具体项目，有时候API和SDK可能是同义的，这里指的是web或rpc api。

常见的构建方式有两种：

  • 一种是嵌入代码的注释或者注解中，然后通过工具来生成文档
  • 一种是直接编写API specification。可以在coding之前编写，然后生成接口代码。

对于Rest API来说，常用的是OpenAPI规范。 对于gRPC API来说，目前似乎并没有类似的规范，但是它也是可以通过OpenAPI暴露服务的，参考grpc-gateway。

Architecture and design details⌗

不是所有项目都需要它们，小团队缺乏足够的资源来产生这样的文档，就将其指向代码。

但是对于多个组件需要彼此配合的项目来说，可能需要介绍下架构和设计的细节。

  • tutorials介绍怎样让这些组件一起工作
  • reference介绍这些组件一起工作的基本原理

虽然有时候我们会直接指向内部的设计文档，但是那对用户来说可能并不太友好。因为内部的设计文档是面向内部的开发人员的，他们和用户所具有的背景知识是不同的。

Security and privacy details⌗

介绍项目内部的加密算法和安全考量。比如

  • 使用什么加解密算法保存密钥
  • 什么时候收集数据
  • 收集数据的目的和方式
  • 数据的存储和处理方式

FAQ⌗

来自于用户反馈的常见的问题，可以解答被重复咨询的问题。

这部分很能会比较繁琐，但可以让其他类型文档保持相对简洁。在有必要的时候，可以将FAQ的内容写道tutorials。

模板⌗

在文档站中，我们会根据文档类型的不同，选择不同的模板。有很多公开的资源可以参考，比如

后续各个模块的各自维护中，各自也可以对模板进行调整。