今天是贝贝报告给你的第 77 天
2019-05-16 星期四

昨天我把项目公开到 Github，架出了文档结构。今天打算填入既有材料，但是却搞不清放在哪里好。

想起来在 FreeCAD 论坛上，有位哥提醒主程 Yorik 看一篇 Divio 上的博客文章，里面指出好的软件文档应有的结构。

教程

• 是学习导向的
• 让新来者开启旅程
• 是一堂课

就像教小孩子怎样做饭

操作指南：

• 是目标导向的
• 展示如何解决特定问题
• 是一系列步骤

就像烹饪书中的食谱

解释

• 是理解导向的
• 说明
• 提供背景和前后环境信息

就像一篇关于烹饪社会史的文章

参考

• 是信息导向的
• 描述了机制
• 准确、完整

就像百科全书的文章

按照这个原则重新架构文档结构，目的明确，思路清晰，真所谓“名正言顺”是也。

英文原文

自说自话的 _sidebar.md， 结构很乱

有功能区分的 _sidebar.md，结构清晰