ShowDoc：程序员写文档的必备工具

## ShowDoc是什么？

你有没有遇到过这种情况：接手别人的项目，打开代码一看，密密麻麻全是没注释的代码，心里瞬间一万匹草泥马奔腾而过。"文档呢？API接口文档呢？数据库说明呢？"然后开始各种找人问，微信群里@来@去，邮件发来发去，最后拿到的还是个过期版本...

简单说，ShowDoc就是一个非常适合IT团队的在线文档分享工具，它可以加快团队之间沟通的效率。不用下载安装任何软件，打开浏览器就能用，支持手机查看，团队协作也很方便。

最关键的是，它专门为程序员设计，知道你们的痛点在哪里。


https://appstore.lazycat.cloud/#/shop/detail/xyz.mxue.showdoc

## 上手指南：5分钟搞定第一个文档

应用安装后，打开语言界面，我们选右侧的中文

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/f6ac73ad-c1fd-4549-bd88-a5b728b04df3.png "image.png")

初始化成功后，会告诉你用户名密码

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/143006c2-16c1-412a-8ef8-1b3172c53297.png "image.png")

点击进入首页

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/676cc2b2-a892-4b9f-b8c5-96e3c4942406.png "image.png")

登录系统

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/2f11aea4-fbab-44f4-b860-5f0530bd24b6.png "image.png")

登录成功后，进入主页面

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/a91149c4-241d-4a05-8433-3e8249a54c0f.png "image.png")

它内置了4种示例模版，可以参考用

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/520d524c-7179-427d-a715-9de4e593463a.png "image.png")

点击"新建项目"，ShowDoc上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问，而私密项目则需要输入密码

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/6f56df99-39e9-4fe6-a55c-73a1e6227330.png "image.png")


**选择建议：**
- 对外的API文档：选公开项目
- 内部技术文档：选私密项目
- 个人笔记整理：选私密项目

点击进入项目，开始写第一个文档，点击"新建页面"

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/508e3229-7ba3-47c1-9d85-c7466ebe5b62.png "image.png")
输入页面标题（比如：用户登录接口）

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/4f489fbb-e876-48a0-b524-d3998fe7392d.png "image.png")

点击编辑器上方的"API接口"按钮，插入模板

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/78bd7325-8c57-460e-be7e-bcf69262c8ad.png "image.png")

填写具体内容，比如：

```markdown
**简要描述：** 
用户登录接口

**请求URL：** 
/api/user/login

**请求方式：**
POST 

**参数：** 

|参数名|必选|类型|说明|
|:----    |:---|:----- |-----   |
|username |是  |string |用户名   |
|password |是  |string |密码   |

**返回示例**
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/77ac236a-6b7f-45a8-add1-1fcaeb3341fa.png "image.png")
点击保存，完成！从项目主页可以看到

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/59d78f49-51d1-43a6-ad65-712969810aad.png "image.png")

ShowDoc有历史版本功能，改错了随时可以恢复。而且可以看到谁在什么时候改了什么，团队协作必备。

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/8d7d2516-b3ae-40a0-a1ce-1df5a16a51dd.png "image.png")

权限管理很贴心

- 项目所有者：可以删除项目、转让项目
- 项目成员：可以编辑文档，但不能删除项目
- 访客：只能查看，不能编辑

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/e34df150-457c-43b1-98be-bd5fc709c8b5.png "image.png")

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/c37b2c12-43bc-4bf0-9fbc-b8de09d3b08f.png "image.png")

导出功能超实用

也可以将项目导出成word文件，以便离线浏览。老板要看文档？直接导出Word给他。需要离线查看？导出到本地随时看。

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/ec4b34be-afd1-49ef-9536-0390030eb2dd.png "image.png")

一份好的数据字典可以很方便地向别人说明你的数据库结构，如各个字段的释义等。
用"数据字典模板"，表名、字段名、类型、说明，一目了然
![image.png](https://dl.playground.lazycat.cloud/guidelines/496/5afbce17-6b82-4f9a-8b7f-167ff24caa7a.png "image.png")
- 可以直接从数据库导出结构，然后粘贴进去稍微调整就行

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/82f4f663-8497-4482-95f1-0c4d7d75216a.png "image.png")
- 新人入职看这个，比看代码效率高100倍

![image.png](https://dl.playground.lazycat.cloud/guidelines/496/78f7ad59-760e-46d7-b61c-4be18f1e37fe.png "image.png")

## 一些实际项目中的使用建议

### 按项目组织文档结构
```
项目名称/
├── API接口文档/
│   ├── 用户模块/
│   ├── 订单模块/
│   └── 支付模块/
├── 数据库文档/
│   ├── 用户表结构/
│   └── 订单表结构/
├── 部署文档/
└── 常见问题/
```

### 写文档时的小贴士
1. **标题要清晰**：让人一眼就知道这个接口是干什么的
2. **参数说明要详细**：必填/选填、数据类型、取值范围都要写清楚
3. **返回示例要真实**：直接复制真实的返回数据，别瞎编
4. **错误码要全面**：各种可能的错误情况都列出来
 
## 总结

ShowDoc就是一个让程序员写文档不再痛苦的工具。界面简洁，功能实用，免费够用，团队协作方便。

如果你的团队还在用Word写接口文档，还在微信群里传来传去找文档，真的该试试ShowDoc了。