These are chat archives for ethereum/homestead-guide
So yeah, the C++ page really is THE DOCUMENTATION for the C++ client, where the others are just our pointers to documentation maintained by the other client teams.
@zelig Do you think it is possible/desirable for the same kind of documentation migration to happen for the Go client documentation? ie. that all of https://github.com/ethereum/go-ethereum/wiki would be moved under http://www.ethdocs.org/en/latest/ethereum-clients/go-ethereum/go-ethereum.html (and edited with loving care at the same time!) That would be cool, but can obviously only happen if the Go team actually WANT that.
We've made this move for the C++ client because chriseth wanted to do that. He (and I) want the same kind of version history and PR/review workflow and "quality bar aspiration" that we want for the source code. We could make made our own new "readthedocs" guide, as already happened for Solidity, but it seemed pointless to make a new "C++ only guide" when the Homestead Documentation Initiative was happening, so moving all C++ documentation under that banner made perfect sense for us. Not sure if the Go team will have the same feeling/aims, but maybe?
WRT to your broad outline suggestion, @zelig, I am not opposed. The challenge is how to make "inlined examples" workable if you want examples in multiple languages. We can't be the first project to hit this, eh? What do Microsoft do for .NET? Where you might have VB.NET, C# or F# examples? Do we need a "toggle" of some kind? Is that even possible? I guess what you really want is a drop-down where the end-user chooses their "language", and that makes the appropriate examples appear. Is that even possible in Sphinx? Or if not, then maybe we do something with putting the examples on their own pages, and have links to them in the main text, ie.
Here is an example of doing X: