3 ms·

I find this to be a common theme with Microsoft products. I work heavily with SSIS and MS SQL. The Microsoft docs are so convoluted they are borderline useless

I find this to be a common theme with Microsoft products. I work heavily with SSIS and MS SQL. The Microsoft docs are so convoluted they are borderline useless for learning the products.

oneplane 5y ago
Same here, and not even GCP is that bad with the 'release' vs. 'beta' APIs that intermingle constantly. Most of the time Azure feels like just another 'we have virtual machines and a crappy API' service. Kinda like a pretend-cloud where a lot of products come almost together but never finish. Almost similar to the way Windows and backwards compatibility means you end up with 100 libraries, frameworks, languages and versions all sitting side-by-side and not really working together, just differently in parallel. Not useful for automation at all, which makes it not useful at scale. (Except when scaling means: we want to run windows VMs with AD and go from 10 to 100 and change no parameters at all)
- spaetzleesser 5y ago
  My theory is that all MS products are ultimately just a layer based on SharePoint :)
  - oneplane 5y ago
    That reminds me of a relatively old twitter thread (that I can't find of course) about systems that have become operating systems and computers upon themselves. It went something like this: Code used to be running on a processor, then it ran on an OS on a processor. Then it became on a runtime on an OS on a processor. Then it an abstraction layer was sandwiched in between. Then a filesystem. Then a compatibility layer. Then a database. Then a browser. Then we went and created a runtime in the browser to run code again. We have come full circle. This probably applies to SharePoint but also the real-time OS on your GPU, the MSSQL database which has its own OS facilities you can run stuff on. Add too many features and the application becomes the very thing we wanted to get away from...
FridgeSeal 5y ago
My friend and I have a theory that this is because their docs are written by people so intimately familiar with how MS does things, they can no longer conceive of a situation where someone doesn’t already understand and think in the same way. It’s like the business equivalent of the “once you understand a monad you can no longer explain it” meme.
- sli 5y ago
  It's Microsoft's modern, less-obvious version of EEE. You sell to the managers and equip them with hollow buzzwords because you know they're gonna override the engineers on every decision anyway. By then, MS has your firm's money and all you can do is deal with it.
- imwillofficial 5y ago
  Or the ole “I tried to explain K8s to a friend, now we both don’t understand it.”
habeebtc 5y ago
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.
- billti 5y ago
  Writing one good set of docs that are suitable for all users (experts and newbies) is really hard. Structuring complex topics in a logical and progressive manner is also really hard. Having tried to write the docs on a few software projects, I honestly found writing the docs harder than writing the code (though maybe it gets easier with practice). I find the Azure docs to be decent. They are consistent across services for the most part, so you learn how to work with them after a bit of experience on the platform.

I find this to be a common theme with Microsoft products. I work heavily with SSIS and MS SQL. The Microsoft docs are so convoluted they are borderline useless for learning the products.

oneplane 5y ago

Same here, and not even GCP is that bad with the 'release' vs. 'beta' APIs that intermingle constantly. Most of the time Azure feels like just another 'we have virtual machines and a crappy API' service. Kinda like a pretend-cloud where a lot of products come almost together but never finish. Almost similar to the way Windows and backwards compatibility means you end up with 100 libraries, frameworks, languages and versions all sitting side-by-side and not really working together, just differently in parallel. Not useful for automation at all, which makes it not useful at scale. (Except when scaling means: we want to run windows VMs with AD and go from 10 to 100 and change no parameters at all)

spaetzleesser 5y ago
My theory is that all MS products are ultimately just a layer based on SharePoint :)
- oneplane 5y ago
  That reminds me of a relatively old twitter thread (that I can't find of course) about systems that have become operating systems and computers upon themselves. It went something like this: Code used to be running on a processor, then it ran on an OS on a processor. Then it became on a runtime on an OS on a processor. Then it an abstraction layer was sandwiched in between. Then a filesystem. Then a compatibility layer. Then a database. Then a browser. Then we went and created a runtime in the browser to run code again. We have come full circle. This probably applies to SharePoint but also the real-time OS on your GPU, the MSSQL database which has its own OS facilities you can run stuff on. Add too many features and the application becomes the very thing we wanted to get away from...

FridgeSeal 5y ago

My friend and I have a theory that this is because their docs are written by people so intimately familiar with how MS does things, they can no longer conceive of a situation where someone doesn’t already understand and think in the same way. It’s like the business equivalent of the “once you understand a monad you can no longer explain it” meme.

sli 5y ago
It's Microsoft's modern, less-obvious version of EEE. You sell to the managers and equip them with hollow buzzwords because you know they're gonna override the engineers on every decision anyway. By then, MS has your firm's money and all you can do is deal with it.
imwillofficial 5y ago
Or the ole “I tried to explain K8s to a friend, now we both don’t understand it.”

habeebtc 5y ago

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.

billti 5y ago
Writing one good set of docs that are suitable for all users (experts and newbies) is really hard. Structuring complex topics in a logical and progressive manner is also really hard. Having tried to write the docs on a few software projects, I honestly found writing the docs harder than writing the code (though maybe it gets easier with practice). I find the Azure docs to be decent. They are consistent across services for the most part, so you learn how to work with them after a bit of experience on the platform.