Document optimization plan

[EvenLjj]

Introduce

It has been more than three years since SOFARPC was open-sourced on April 10, 2018. RPC-related documents are mainly updated in June 2019. At that time, the document was relatively classic, and the core functions of RPC were introduced relatively clearly. However, with the iterative update of functions and the update of related components, according to the documents, we found that there are some areas that are not up to expectations. Many committees have also raised issues with problems that we have dealt with, and some may not have been dealt with. In order to have a better user experience, the previously scattered issues related to document optimization or document optimization can be collected and processed together. We have collected some common issues and plan to optimize them. At the same time, we hope to use the power of the community to work together to create a better SOFARPC. You can throw out here the problems you encounter when using the document. We will update the document optimization task from time to time in the follow-up. Welcome everyone to build together.

Optimization task

Registry

• Use SOFARegister as a registration center document optimization (related issue Error occurred during quick start with sofa-registry #1029) Already assigned to @EvenLjj
• Use Zookeeper as a registration center document optimization (Related issue zookeeper无法连接 #1113)
  • Added Zookeeper construction guidelines, and added Zookeeper client version instructions
  • FAQ supplement
• Use Nacos as the registration center document optimization (related issue 服务注册nacos不成功 #1023 sofaboot集成nacos作为注册中心并同时使用nacos-discovery异常 #1101)
  • Nacos 2.0 related access instructions
  • FAQ supplement

Configuration instructions

• Improve the clarity of RPC-related configuration instructions, more user-friendly (related issue Improve the documentation of configuration parameters #1030)
  • Provide configuration default value, measurement unit and configuration format requirements

---

背景

SOFARPC 从2018年4月10号开源至今已经三年多了，RPC相关的文档主要还是2019年6月份更新的文档为主，当时文档编写的还是比较经典的，将RPC的核心功能都介绍的比较清楚。不过随着功能的迭代更新，以及关联组件的更新，目前根据接入文档发现有一些不达预期的地方，很多同学也将遇到的问题提了issue，有的我们处理了有的可能还没来得及处理。为了更好的用户体验，将之前零散的关于文档优化或者可以优化文档解决的issue集中到一起处理，我们收集了一些共性问题，打算着手优化下，同时也希望借助社区的力量一起共同打造更好的 SOFARPC。大家可以将平时按照文档使用时遇到问题在这里抛出来，后续我们会不定期更新下文档优化任务，欢迎大家一起共建。

优化任务

注册中心使用

• 使用SOFARegister作为注册中心文档优化 （相关issue Error occurred during quick start with sofa-registry #1029）Already assigned to @EvenLjj
• 使用Zookeeper作为注册中心文档优化 （相关issue zookeeper无法连接 #1113）
  • 添加Zookeeper搭建指引，以及添加Zookeeper客户端版本说明
  • 常见问题FAQ
• 使用Nacos作为注册中心文档优化 （相关issue 服务注册nacos不成功 #1023 sofaboot集成nacos作为注册中心并同时使用nacos-discovery异常 #1101）
  • Nacos 2.0 相关接入说明
  • 常见问题FAQ

配置说明

• 提升RPC相关配置说明的清晰度，对用户更友好 （相关issue Improve the documentation of configuration parameters #1030）
  • 提供配置的default值、度量单位以及配置格式要求

[MingJunDuan]

Document is very important, how can we contribute to it, markdown or other?

[EvenLjj]

Document is very important, how can we contribute to it, markdown or other?

The Chinese original docs address is https://github.com/sofastack/sofastack.tech/tree/master/content/zh/projects/sofa-rpc in markdown. You can sumit PR to the repository. Recently, we are preparing to migrate the original documents to the repository of sofa-rpc.

[MingJunDuan]

https://github.com/sofastack/sofastack.tech/pulls 社区有人处理文档吗，135个PR没人处理，现在的文档资料少，而且有些也跟不上代码的迭代 @EvenLjj

[EvenLjj]

看了下大多 PR 是社区会议记录的文档，这些 PR 我们看看放到哪里比较合适。SOFARPC 这块一些新的功能文档，还没补充。正好最近SOFA 6周年也谈到文档这块的维护问题，我们也看看怎么把这个文档维护的机制搭建起来。