[jlarocco]

> It’s pretty clear if you check github that Azure’s services and documentation are written by distributed teams with little coordination. We have a saying in-house that the info is all in their docs, but the sentences and paragraphs for even trivial things are split across ten or fifteen articles.

You can say that for the APIs themselves. It's like every API call has 80% of the info I want, but the other 20% that logically belongs with that 80% has to come from multiple other API calls.

The one that annoys me on a daily basis is fetching the logs for a pipeline run. The endpoint is `_apis/build/builds/<id>/logs` and it returns a list of pipeline log objects without the task name that generated them. You get an object with these fields: `{"lineCount", "createdOn", "lastChangedOn", "id", "type", "url"}` but no mention of the pipeline stage that generated it.. whether it's the build step, test run, publishing stage, etc. And those ids change (for example if you re-run a failed job, the unit tests may have ID 4 from the first run, and ID 17 for the second try), so you can't just rely on that.

And the pipeline log viewer on the website is garbage. When you click the link to view the logs it doesn't show you the logs it's collected already but starts showing new logs from that point forward and even for that, sometimes it truncates output and will skip lines. Somehow they managed to make trawling through logs even worse than it would normally be.