[d_burfoot]

Gah, choke, barf.

Crowd-sourcing is not the right way to document a big complex software suite.

The right way is to use special software to compile or extract the documentation from the underlying source code. The documentation generator should be conceptually similar to a Jupyter Notebook or a Mathematica Computable Document.

Furthermore, the documentation generator should run actual code that throws an error if there's a mistake. For example, in this document:

https://github.com/awsdocs/aws-cli-user-guide/blob/master/do...

The CLI operations should be lifted from some other file, and that other file should get run as a test by a CI tool, so that when there's a change to the CLI, it's automatically flagged for correction.

[vasco]

While for docs which are very close to code, you're right, good documentation has a lot of things at much higher level than code, and a lot of times teaching people how to do things unrelated to the actual implementation, ie "how to expand a linux file system after you increased an EBS volume". Your comments are a bit reductionist.