What about documentation, even "how-to use this product" documentation, that's generated from the code's comments directly? So say you have a function that ess

What about documentation, even "how-to use this product" documentation, that's generated from the code's comments directly? So say you have a function that essentially implements the "--file" flag: what if the developer put a comment above this function explaining the function's purpose but also the documentation for the admin's use case, which would be setting up the solution? I believe that if such documentation existed it would be a lot easier to update it when the code is changed (provided the API changes) and have it propogate through to the docs. The comments could also be three tiered: API docs, admin docs, user docs; each would explain to the relevant user how-to make use of the code at that point. Obviously you could omit user/admin comments for functions that aren't "public facing", such as internal helper functions. But anything that's directly interacted via a CLI flag or HTTPS endpoint could have the documentation right there by the code handling that interaction... or not if it's not relevant. See "godoc" as an example of this: https://blog.golang.org/godoc-documenting-go-code https://blog.golang.org/godoc-documenting-go-code The code truly does become the documentation at this point, and acts as a central point of truth.