1. Remove the "Run" section from https://docs.cometbft.com/v0.38/guides/install. The "Quick Start" guide does a much better job explaining what is happening, and readers should follow that guide instead.
2. It would be great if code blocks had a "copy" icon, freeing developers from the need to select and copy text manually. moving to https://github.com/facebook/docusaurus should solve this
3. https://docs.cometbft.com/v0.38/guides/quick-start#cluster-of-nodes. Getting an ID from every machine is tedious and can be streamlined with a script, which, given IPs, collects IDs and outputs the command to run CometBFT.
4. No reason to have “CometBFT Quality Assurance” as a second item. The target audience for that document is probably security researchers - not the primary audience.
5. https://docs.cometbft.com/v0.38/app-dev/abci-cli#kvstore---first-example Replace cmdKVStore code with a link. I can’t see a single reason why users need to see the source code of that function in order to progress with the abci-cli tool.
6. https://docs.cometbft.com/v0.38/app-dev/getting-started#first-cometbft-app should go before https://docs.cometbft.com/v0.38/app-dev/abci-cli because the latter is used to test ABCI applications. And by this point, the reader doesn’t have an app to test.
7. https://docs.cometbft.com/v0.38/core/using-cometbft#run Why are we connecting to TCP by default if it’s not secure (see https://docs.cometbft.com/v0.38/app-dev/app-architecture where we explicitly say so). How about connecting to the UNIX socket by default?
8. https://docs.cometbft.com/v0.38/core/validators “Validators are expected to be online, and the set of validators is permissioned/curated by some external process.” This sentence is confusing to me. The set is curated by the ABCI application.
9. “Committing a Block” not clear what’s the reason of explaining consensus details in the validators section. If a validator wants to get familiar with consensus, shouldn’t it go to consensus spec / page?

cc @andynog