Favor Explanations Over Blind Code via Community Expert Annotations #495
Description
Main suggestions content
It is recommended to accept some explanation of docs content from community professionals and use these explanations as docs annotations.
Reason
Sometimes, when new developers read these docs, they encounter sections that are difficult to understand. As a result, they often resort to using the docs only as a supplementary resource and turn to the community to find tutorials created by community experts. However, the docs are crucial to the entire development process. Most tutorials do not cover all the content of the docs or omit certain details, so developers still need to refer back to the docs—only to face the aforementioned "difficult to understand" issue again. Let me give an example:
Here, new developers understand that the docs instruct them to use this code snippet as their item class. However, even after following the instructions, they still fail to comprehend certain parts of it.
What I mean is that the docs sometimes lean toward low-level descriptions, which can be unfriendly to some new developers. This is where the community can play a vital role. We can incorporate explanations provided by community experts regarding the docs and use these explanations as annotations for the docs. Since such explanations are tailored specifically for new developers, they are far more accessible. This approach not only better promotes the growth of both the community and the docs but also creates a win-win situation, in my opinion.
Please consider adopting my suggestion. Thank you.