这篇文档列出了为 Gandi IDE 新建与更新文档的工作流。
目前,Gandi IDE 的文档使用 Notion 创作,并通过 Super App 的服务呈现在 getgandi.com 网站中。这篇文档中会包含在创建与维护文档时,这两个工具中的主要操作。
Create a new document
一般有三种情况需要创建新文档:
- 新功能上线;
- 添加新的最佳实践;
- 添加新的社区及贡献条款;
在创建新文档时,可以参考以下工作流。
参考 Content guidelines 确定文档的类型
为了方便创作者检索文档,我们制定了 Gandi IDE 的文档目录结构。
在创建新文档时,请先根据文档的内容,参考 Content guidelines,确定文档在目录结构中的位置,再进入下一步创建文档。
>> Content guidelines
在 Blog Database 中创建一个新条目
确定文章在目录结构中的位置后,在 Notion 的 Blog Database 中新建条目。
Blog Database 中的文档是以 type 进行分组的。
Step 1: 在 No Type 中新建一个文档
Step 2: 根据目录结构选择 Type。
Database 中的文档属性:
- Type:文档类型,对应文档目录结构中的位置;
- Area:文档的曝光位置;
- Tags:文档标签,部分文档曝光位置中会显示,提示用户文档可能包含哪些方面的内容;
- Features:文档内容涉及到的功能,一般不会呈现给用户,便于在功能更新时检索待维护文档;
- Description:文档简介,部分文档曝光位置中会显示,概括文章的主要内容;
- Note:
- Status:文档状态;
- To-do:新建文档;
- Outdated:对应功能已更新,需要更新文档;
- Reported:发现文档中有 bug,需要修复;
- Writing:正在写作中;
- Proofreading:校对中;
- Up-to-date:文档为当前版本的最新状态;
文档写作与校对
条目创建好之后,开始文档写作,将文档状态设置为 Writing。
文档写作过程中的注意事项,参考 Writing guidelines。
写作完成后,将文章状态设置为 proofreading,在社群发起 proofread 任务,招募用户校对文章内容。具体方法参考 Writing guidelines。
>> Writing guidelines
SEO 设定
调整文档的 SEO 设定,可以帮助潜在用户在搜索引擎中找到我们,
在 Super App 中修改文档的 SEO 设定。
URL 设定
Title 设定
SEO 设定完成后,将文档的状态修改为 Up-to-date。
文档展示设置
在 Notion 的其他页面中,可以通过创建 gallery 来展示 Blog Database 中的文档。
Step 1: 创建 gallery
Step 2: 选择 Area 筛选项
Step 3: 设置显示方式
Update a document
一般在两种情况下更新文档:
- 有关于文档的 bug report;
- 文档对应的功能更新了;
在更新文档时,可以参考以下工作流。
检查文档状态
确定功能更新后,检索文档的 Features 属性,找到包含该功能的所有文档,将文档状态设置为 Outdated,将已更新的功能记录在 Note 中。
收到关于文档的 bug report 后,检索到对应的文档,将状态修改为 reported,将 bug report 的相关内容添加到 Note 中。
更新内容与校对
更新 Outdated 文档后,修改内容较少的情况下,可以自行校对,有大范围的更新时,可以发起社群的校对任务,招募用户协助校对。
更新 Reported 文档后,需要反馈给 report bug 的用户,告知用户问题已修改,并邀请对方确定修改后的内容。
文档更新后,将文档的状态设置为 Up-to-date。