文档目录设计讨论

[printfcoder]

[Jinof]

目标(定位):

stack-rpc 基于Go Micro 和 Go Zero 的微服务框架. 提供服务治理能力, 让程序员聚焦业务.

需求

1. 一个开源微服务框架的文档需要提供给使用者什么?
2. 读者更容易接受什么样的文档

对需求的回答

1. a. 使用场景 b. 使用方法
2. a. 可读(语言简练) b. 渐进(由简单到复杂) c. 全面(丰富的例子) d. 可信(例子可在不修改的情况下执行)

由需求1此可得出的目录

	.
	├── introduction  // 介绍使用场景
	└── usage  // 提供使用方法

如何组织使用方法？

将每个常用的API单独开辟一个目录并提供相应的说明和例子, 同时应该提供一份索引. 那么usage将变成下面的样子

	.
	├── README.md  // 提供索引到各个API, 并且应该有对每个API的简要说明
	└── web
	    ├── README.md  // 详细介绍该API
	    ├── web.go  // 使用样例
	    └── web_test.go  // 测试样例

但是这样子的组织方式不够入门, 初学者往往会在看API的途中迷失了自己. 应该提供一个足够大的例子, 将框架的重要概念讲清楚, 这样他们在学习API就接受得更快. 那么应该将这个例子放在usage之前.

	.
	├── introduction
	├── key_concept  // 一个足够大的介绍stack-rpc重要概念的例子
	└── usage
	    ├── README.md
	    └── web
	        ├── README.md
	        ├── web.go
	        └── web_test.go

结论

	.
	├── introduction  // 介绍使用场景
	├── key_concept  // 一个足够大的介绍stack-rpc重要概念的例子
	└── usage(API REFERENCE)  // 提供使用方法
	    ├── README.md  // 提供索引到各个API, 并且应该有对每个API的简要说明
	    └── web
	        ├── README.md  // 详细介绍该API
	        ├── web.go  // 使用样例
	        └── web_test.go   // 测试样例

[david-hw]

目标:

• 简洁，直观，渐进

• 从解决实际问题出发，一个样例解决一个实际场景问题

方案：

.
├──README.md  // 提供索引到各个场景, 并且可根据开发、部署等分组
└── DEMO1 // 特定场景，如：解决开发人员快速入门
	├── README.md  // 介绍该示例主要解决的实际问题，以及用到主要框架知识介绍
	├── web.go  // 使用样例
	└── web_test.go   // 测试样例
└── DEMO2 // 特定场景，如：解决开发人员快速入门
	├── README.md  // 介绍该示例主要解决的实际问题，以及用到主要框架知识介绍
	├── user-srv
		├── web.go  // 使用样例
		└── web_test.go   // 测试样例
	├──user-api  
		├── web.go  // 使用样例
		└── web_test.go   // 测试样例
	└── main.go  

[yaoyaoio]

前言

• 框架介绍
• 框架特性
• 贡献指南
• 版本规划

快速开始

• RPC
• HTTP

服务端

• RPC
• HTTP

服务发现注册

• Etcd
• Consul
• kubernetes

日志

• Logger

异步消息

• Kafka
• MQ

服务熔断降级

• hystrix

服务限流

• hystrix

配置管理

• Config
• Apollo
• Consul
• Etcd

部署

• Docker
• Kubernetes

调用链监控

• OpenTracing
• Jaeger
• Skywaling

Metric监控

• Promethues

[printfcoder]

所以我们的文档要聚焦在：

• 框架是什么
• 框架的组件及配套
• 框架Demo

个人补充一点：

• 博客

我们是要有我们的使用经验分享专栏，任何技术栈都可以

[printfcoder]

@Jinof @david-hw 我觉得可以按@yaoliu的思路来设计大纲，然后增加一个栏目为教程，教程里放各种Demo。怎么样？如果可以我们就在这基础上细化每个点，然后开始写了

[Jinof]

@Jinof @david-hw 我觉得可以按@yaoliu的思路来设计大纲，然后增加一个栏目为教程，教程里放各种Demo。怎么样？如果可以我们就在这基础上细化每个点，然后开始写了

ACK

[david-hw]

@Jinof @david-hw 我觉得可以按@yaoliu的思路来设计大纲，然后增加一个栏目为教程，教程里放各种Demo。怎么样？如果可以我们就在这基础上细化每个点，然后开始写了

赞成

[printfcoder]

@Jinof @david-hw 二位可以微信私聊我一下哈，v: SLliuxian。咱们可以开始写了哟，服务基本可以编写了。我们在写demo和文档时顺道再覆盖测试一遍。

[printfcoder]

一期文档主要目录：https://github.com/stack-labs/stack-labs-site/blob/master/docs/resources.zh-CN.md