I find the problems with Microsoft docs is less how convoluted they are (you kind of get used to the convention at some point - not to say it's good or sensical), it's the fact that Azure documentation is not of the same quality that the WinAPI docs were.
Used to be a function doc would tell you:
1. All the parameters and their types
2. What they did, explained
3. All possible exceptions raised by the function
4. All possible return values
5. Supplementary documentation on the object or structs passed in or passed back
6. Some examples of it in use
Now, the current docs sometimes have examples for Azure CLI/SDK stuff, but there is one convention that drives me bonkers that is as bad now as it ever was.
For examples, often times you'll get the most important part replaced with a [insert your thing here]. The format of the thing you fill in there is often left as an exercise to the reader to intuit or guess.
Used to be a function doc would tell you:
1. All the parameters and their types 2. What they did, explained 3. All possible exceptions raised by the function 4. All possible return values 5. Supplementary documentation on the object or structs passed in or passed back 6. Some examples of it in use
Now, the current docs sometimes have examples for Azure CLI/SDK stuff, but there is one convention that drives me bonkers that is as bad now as it ever was.
For examples, often times you'll get the most important part replaced with a [insert your thing here]. The format of the thing you fill in there is often left as an exercise to the reader to intuit or guess.