WIP: :memo: Docs: 修改文档

yixinNB commented 6 days ago

根据这几天纯小白看官方文档所感, 对文档进行修改.

对文档做出的修改:

这是一个初稿且正在完善, 欢迎给出建议, 请暂时不要merge.

如果能接受我的文档风格, 请告知我. 我将继续完善文档

yanyongyu commented 6 days ago

当初就是大多数人不喜欢技术性文档才改成的教程，你这是再改回去吗？

另外api文档搜不到是algolia爬取的问题，这个问题已经在解决中了。

另外补充一下，修改文档请修改docs目录，不要修改历史版本。

github-actions[bot] commented 6 days ago

yixinNB commented 5 days ago

当初就是大多数人不喜欢技术性文档才改成的教程，你这是再改回去吗？

另外api文档搜不到是algolia爬取的问题，这个问题已经在解决中了。

另外补充一下，修改文档请修改docs目录，不要修改历史版本。

首先回复你的回复: 我认为教程是提供给初学者看的, 在实际开发中经常需要快速查阅. 就我实际体验来看, 需要在"指南/深入/进阶"中反复横跳. 我不反对教程式的文档, 但是我希望文档应该做好超链接和上下文的说明

我认为当下文档有以下提升空间:

文档的分散和上下文的缺失 例如"响应规则"在指南/深入/进阶里面都有涉及

以上改进首先要方便学完以后快速查找, 其次也能方便喜欢跳着读文档的人

请进一步给出建议

yanyongyu commented 5 days ago

部分 import 缺失可能是疏忽的原因，但是大部分内容都是连贯的。至于你说的部分内容在两个层级都有提到，因为那是完全不同的用法，根据教程的进度安排在不同章节提及。在现有文档上增加深入部分链接这个确实可以完善。

至于你说的快速查找，我不是很明白你的快速查找是什么阅读方式，个人认为搜索已经能够满足阅读需求。

另外补充一点，文档是书面化的表述，请避免口语化语句的出现。

yanyongyu commented 3 days ago

algolia 搜索已暂时恢复，会在下个 doc 主题版本彻底解决。