ProfessorProfessor1 hour ago, Sarah Terry said:@Cole McDonald @Joe Tran we will improve the documentation for this endpoint - thanks!
Thank you. The part I found confusing mostly was the example code given... it is just a generic, blank JSON block. Had that had more detail, I'd have been able to figure it out more quickly.
When I've done documentation for Functions and Objects in the past, I've always made sure to include expected input and output... not just types, but structural so that anyone can drop in on my code and be able to produce results immediately. Most of what I've done in the past has been internal tooling, so I saw it as cost savings for the company I was working for due to reduced dev time. I don't tend to see that level of documentation for APIs elsewhere. All of MS's dev docs miss this as well. I've commented on it and they've stated that it was a common complaint. Their new documentation is much clearer, but most of their offerings are still the old documentation style; just giving the function names and leaving it to the developer to parse their meaning/usage.
