改进文档（wiki）

[xlucn]

总的想法就是文档应该改进为更加规范、更加严谨、更加有条理的形式。

目前的文档（指wiki）有诸多的问题。从很多issue说文档看不懂、找不到文档就可以反映出来。#515 还更一般地建议改进，但是被开发者不知原因关掉了。我将发现的大方面的问题列举如下：

• 位置分散。
  • 除了wiki内部的文章，wiki中还包含指向gist的链接。
  • 还有一些文档散落在其它的仓库中。甚至有些貌似没有文档（或者很难找到），比如配置ibus-rime只能参考仓库中的ibus_rime.yaml文件，可一般用户不会第一时间想到看源文件。
  • 重复和缺失。比如系统文件夹和用户文件夹在Configuration中指向了两篇独立的文章；而RimeWithSchemata中依然再次介绍它们的位置和内容。
• 逻辑分散，没有完整的架构。这个是最严重的。
  • 文档不完备。就总的文档分布来说，比如讲配置文件的，貌似有两篇：Configuration和CustomizationGuide。前者讲的是rime配置文件所接受的格式，后者讲的是定制，即怎么写custom.yaml文件去影响部署后得到的配置文件。但是，没有文章完整地列举rime以及一些核心和周边的包（如不同平台/引擎）所有的可设置项。所以用户知道怎么写，怎么改，但是不太容易找到可以改什么。
  • wiki没有对所有页面进行排序、分章节。可以使用sidebar进行分类整理，比如哪些是面向用户的，哪些是面向开发者的；面向用户的里面，哪些是一般性配置，哪些是针对特定平台/框架/引擎的，哪些是周边如用户词典，等等。
  • 就单个文档来说，目前的文档，比如CustomizationGuide，里面全部都是以分散的案例形式展现的。这一是有上面说的文档不完备的问题，另外用户也很难快速找到想要的那一个设置项。我认为如果做到了上面提到的完整列举所有设置项，这种案例的形式可以大幅削减。
• 语言用词比较随便。当然这个可能属于个人习惯、甚至是地区的说话习惯。但我觉得大体上wiki里的用语用词还是很生活化、甚至艺术化，这对于一个技术文档来说，是有副作用的。

[lotem]

文檔​可以視爲未完成狀態。