1) You involve the API consumers in the design and decision process, which helps in understanding their use cases better.
2) Give insights and transparency to consumers as to why and how some decisions were made about the API.
You want to comment on the API docs using the API itself? The goal is to let you fork the specs and issue a pull request on GitHub.
> Tooo many times I googled for an answer that the API docs neglect and found the answer instead on StackOverflow.
Are you referring to the API docs for Balanced or API docs in general?
Forking the specs sounds good.
Meant the lacking in answers for API docs in general. Especially facebook in the past; though Graph Explorer is much nicer!