​
背景

Cosmos SDK 文档需要一种可扩展的结构。当前文档包含了大量与 Cosmos SDK 无关的内容，维护困难，用户阅读和跟进也比较吃力。 理想情况下，我们希望：
  • 所有与开发框架或工具相关的文档都放在各自对应的 GitHub 仓库中（sdk 仓库包含 sdk 文档，hub 仓库包含 hub 文档，lotion 仓库包含 lotion 文档，等等）
  • 其他所有文档（FAQ、白皮书、关于 Cosmos 的高层材料）都放在网站上。

​
决策

按如下方式重构 Cosmos SDK GitHub 仓库中的 /docs 文件夹： 
docs/
├── README
├── intro/
├── concepts/
│   ├── baseapp
│   ├── types
│   ├── store
│   ├── server
│   ├── modules/
│   │   ├── keeper
│   │   ├── handler
│   │   ├── cli
│   ├── gas
│   └── commands
├── clients/
│   ├── lite/
│   ├── service-providers
├── modules/
├── spec/
├── translations/
└── architecture/
每个子文件夹中的具体文件并不重要，而且之后很可能会变化。重要的是分区方式：
  • README：文档的入口页。
  • intro：入门材料。目标是先提供一份简短的 Cosmos SDK 说明，再把用户引导到他们需要的资源上。这里会重点展示 Cosmos SDK tutorial 以及 godocs。
  • concepts：包含对 Cosmos SDK 各种抽象的高层说明。不包含具体代码实现，也不需要频繁更新。它不是这些接口的 API 规范。API 规范应以 godoc 为准。
  • clients：包含各种 Cosmos SDK 客户端的规范和信息。
  • spec：包含模块规范及其他规范。
  • modules：包含指向 godocs 的链接以及各模块的规范。
  • architecture：包含像本文这样的架构相关文档。
  • translations：包含文档的不同语言翻译。
网站文档侧边栏只包含以下部分：
  • README
  • intro
  • concepts
  • clients
architecture 不需要在网站上展示。

​
状态

已接受

​
影响

​
正面影响

  • Cosmos SDK 文档的组织结构会清晰得多。
  • /docs 文件夹现在只包含 Cosmos SDK 和 gaia 相关内容。后续将只保留 Cosmos SDK 相关内容。
  • 开发者在提交 PR 时只需要更新 /docs 文件夹（例如不再需要更新 /examples）。
  • 由于架构经过重构，开发者更容易找到自己需要更新的文档内容。
  • 网站文档的 vuepress 构建会更加整洁。
  • 有助于构建可执行文档（参见链接）

​
中性影响

  • 我们需要把一批已弃用的内容移到 /_attic 文件夹。
  • 我们需要将 sdk/docs/core 中的内容整合进 concepts。
  • 我们需要把当前位于 docs 中、但不符合新结构的所有内容（如 lotion、入门材料、白皮书）迁移到网站仓库。
  • 更新 DOCS_README.md

​
参考

​
Context

There is a need for a scalable structure of the Cosmos SDK documentation. Current documentation includes a lot of non-related Cosmos SDK material, is difficult to maintain and hard to follow as a user. Ideally, we would have:
  • All docs related to dev frameworks or tools live in their respective github repos (sdk repo would contain sdk docs, hub repo would contain hub docs, lotion repo would contain lotion docs, etc.)
  • All other docs (faqs, whitepaper, high-level material about Cosmos) would live on the website.

​
Decision

Re-structure the /docs folder of the Cosmos SDK github repo as follows: 
docs/
├── README
├── intro/
├── concepts/
│   ├── baseapp
│   ├── types
│   ├── store
│   ├── server
│   ├── modules/
│   │   ├── keeper
│   │   ├── handler
│   │   ├── cli
│   ├── gas
│   └── commands
├── clients/
│   ├── lite/
│   ├── service-providers
├── modules/
├── spec/
├── translations/
└── architecture/
The files in each sub-folder do not matter and will likely change. What matters is the sectioning:
  • README: Landing page of the docs.
  • intro: Introductory material. Goal is to have a short explainer of the Cosmos SDK and then channel people to the resource they need. The Cosmos SDK tutorial will be highlighted, as well as the godocs.
  • concepts: Contains high-level explanations of the abstractions of the Cosmos SDK. It does not contain specific code implementation and does not need to be updated often. It is not an API specification of the interfaces. API spec is the godoc.
  • clients: Contains specs and info about the various Cosmos SDK clients.
  • spec: Contains specs of modules, and others.
  • modules: Contains links to godocs and the spec of the modules.
  • architecture: Contains architecture-related docs like the present one.
  • translations: Contains different translations of the documentation.
Website docs sidebar will only include the following sections:
  • README
  • intro
  • concepts
  • clients
architecture need not be displayed on the website.

​
Status

Accepted

​
Consequences

​
Positive

  • Much clearer organization of the Cosmos SDK docs.
  • The /docs folder now only contains Cosmos SDK and gaia related material. Later, it will only contain Cosmos SDK related material.
  • Developers only have to update /docs folder when they open a PR (and not /examples for example).
  • Easier for developers to find what they need to update in the docs thanks to reworked architecture.
  • Cleaner vuepress build for website docs.
  • Will help build an executable doc (cf Link)

​
Neutral

  • We need to move a bunch of deprecated stuff to /_attic folder.
  • We need to integrate content in sdk/docs/core in concepts.
  • We need to move all the content that currently lives in docs and does not fit in new structure (like lotion, intro material, whitepaper) to the website repository.
  • Update DOCS_README.md

​
References