我为了做一个小众的项目去编写GitBook文档时, 第一次真的把自己搞晕了, 当我把智能合约中的每一个函数的内容都仅仅像抄写员一样照搬记录下来的时候, 任何读者只要翻阅了两页内容就会立刻离开, 因为文档并不是代码注释的简单替代, 你需要站在读者的角度用通俗的语言帮他们把事情背后的缘由和动机解释清楚。
对于当前的写作习惯, 我会在每一章节的起始位置先抛出一句大白话, 这句话的意思是“这一页面讲述的是如何把以太坊兑换成您自己的代币”, 紧接着就会附上代码部分, 这整个流程的操作感觉就像是在使用 gitbook 作为项目文档工具的时候, 它的作用更像是这个项目的食堂菜单一样, 你当然不能仅仅只写上像“3号锅”这样含糊不清且令人费解的字眼, 而是应该清晰地写明具体的菜品名称是“宫保鸡丁”。
在设计结构的时候, 不要把功能点罗列得特别多。要在首页的位置放上一个清晰的整体路线图, 在专门给开发者看的区域里把部署的过程详细说明一下, 在面向普通用户的区域内则主要讲解钱包应该如何进行连接操作。
一旦导航的层级超过了三个级别, 基本上就没有多少人愿意继续往下浏览了。不管你的目录树设计得有多么深邃复杂, 也抵不过人们用手指滑动屏幕时没有耐心的现实情况。
有人提出来了项目这一回事，让我把这个白皮书也给塞进去, 我就劝你别这么做, 因为白皮书是宣传册, gitbook是说明书, 把这两样东西混在一块儿的话, 就是两头都不讨好。
