微文档: 相比以 ReadtheDocs 为代表的传统文档,微文档在写作、阅读、搜索、分享、交流等方面,更加轻量化。
以 Python 官网文档为例,对比体验:
文档内容:Python3.6 中文教程(总共 16 章,大约 15 万字),微文档合并 16 章完整内容,全文加载,自动生成章节目录。
VS | 传统文档 | 微文档 |
---|---|---|
写作 | 按章节划分,多篇写作 | 一篇文章,写作更轻松 |
阅读 | 分页阅读 | 全文加载,单页阅读,沉浸式体验 |
搜索 | 后端 | 前端 (页内查找、ctrl+F) |
讨论 | 不方便 | 学习交流,方便讨论 |
适宜 | PC 阅读 | 特别适宜手机 /Pad 阅读,兼具 PC。 |
微文档只包含一篇文档,非常简单!一般由 4 个部分:文档名称、简介、目录及内容。开头第一行是 “# 文档名称”,下面是文档简介,文档目录由系统自动生成(以 # 开头的标题,是文档目录 /子目录)。例如:
文档名以 # 开头,如:# 文档名称
标题以 ## 开头,如:## 1 这是第 1 篇标题
子标题以 ### 开头,如:### 1.1 这是第 1 篇标题的子标题
1
qiayue 2019-10-07 09:44:44 +08:00 1
PC 端建议增加左侧目录,不然不好快速切换章节
|
2
CoderLife 2019-10-07 10:59:15 +08:00
不太好用
|
3
lonccc 2019-10-07 11:27:01 +08:00 via Android
我觉得挺好的呀,适合新手
|
4
17681880207 2019-10-07 14:26:34 +08:00
左侧的目录树没的吗?无法快速定位
|
5
FakeLeung 2019-10-07 15:43:41 +08:00
左侧目录+1.
|
6
ooops 2019-10-07 16:01:39 +08:00
点左下角的目录回到顶部的交互有点太不友好。
|
7
xiaotuzi 2019-10-08 08:30:57 +08:00 via iPhone
改天我准备把看云的文档导出来做成 chm😂适合 PC 端阅读。
|
8
azoon 2019-10-08 11:59:02 +08:00
没有左侧目录已经够反人类了
|
9
balabalaguguji 2019-10-08 19:17:37 +08:00
看下 easydoc.top 似乎更好用
|
10
okwork 2019-10-08 20:36:04 +08:00
@balabalaguguji 这个不错,带左侧目录,有 2 个问题:能不能目录弹出不要完全覆盖正文,Material Design 推荐是覆盖 2/3 左右;另外能不能把“目录”按钮放左下角,每次手要够到左上角,很不方便。
|