Documentation is as important as codes I think, it’s a way of showing the attitude that people are welcomed to use the library.
I helped with the Nervos p2p library translation, but not sure if the description is precisely enough. I had the problem with understanding the Chinese description that is easy to be misunderstood. Because I didn’t involve in the library as well as its usage, so I am not so clear about its implementation logic. Especially, writing documentation for human beings is totally different than programming, which is written instructions for machines. It’s also a challenge for developers.
Also, sometimes you need to overcome the lazy, that many concepts only exist in our mind but not in the mind of the audience. So you need to write down every detail, like to guild a newcomer to your house. An introduction is a need at the very beginning, such as directions, locations, distance, etc. Then the tutorial, if he drives, then let him know when will be the next step, how the road will be, which way will be better, he will see some stores, turn right at a bank, then he will see a row of restaurants, stop at the end of the road, parking. Just like that. You just can’t leave a big space to let him imagine on himself.
So to speak, every name should be clearly defined as basic, then explain the relationships, and then the whole logic. Explain one logic at a time until there is nothing to explain. All words should be clear and plain.
The second version of p2p documentation is much better than the old version 6 weeks ago, and there still space for optimization. Hope I helped this time, at least there is an entrance for English readers.
We need more documentation, see Nervos CKB GitHub.