Right now, we have all technical specs under each module's x/{module}/spec directory and docs for APIs and CLIs are located under docs directory. This is confusing for new developers and people who want to learn about our modules. I suggest to combine them into a single directory (preferably in each module's spec direcotry) so that new developers don't need to move around to find what they want. Also, it will be better to give guidance about what each module does in one or two sentences by having central README.md file in x/ directory.
Suggestion
Combine technical docs into a single directory (preferably in each module's spec directory)
Create a central README.md file that describes what each module does in x/ directory
Have same format for all api and cli docs
Consideration
We need to update the changed links if we decide to change some docs to other directories so that sites are up to date.
Summary
Right now, we have all technical specs under each module's
x/{module}/specdirectory and docs for APIs and CLIs are located underdocsdirectory. This is confusing for new developers and people who want to learn about our modules. I suggest to combine them into a single directory (preferably in each module'sspecdirecotry) so that new developers don't need to move around to find what they want. Also, it will be better to give guidance about what each module does in one or two sentences by having centralREADME.mdfile inx/directory.Suggestion
specdirectory)README.mdfile that describes what each module does inx/directoryapiandclidocsConsideration