4 ms·

Well, PowerShell docs are next to useless. Maybe the other parts are better. But I think this mythos of great docs for proprietary MS stuff is just that, a myth

by pas 5y ago

Well, PowerShell docs are next to useless. Maybe the other parts are better. But I think this mythos of great docs for proprietary MS stuff is just that, a myth.

fiddlerwoaroof 5y ago
Yeah, I’ve tried a handful of Microsoft products and MSFT’s docs are ok for tutorials, but I’ve often found it hard to find useful reference documentation: e.g. the tutorial bits of Appcenter’s Codepush and UI Testing documentation are ok, but the reference documentation for both is ambiguous and/or incomplete.
- radicalbyte 5y ago
  With Microsoft, generally the documentation around the edges isn't great. The edges being the "Microsoft condoned solutions and generally anything coming from the Office/Enterprise side. On the Enterprise side they often have fantastic documentation but they have an amazing talent for making it unfindable. It's like they hire an army of noob-level interns who churn out "getting started" articles, with the end result being that you have to dig 5 pages deep into Google result to get meaningful documentation (4 of those pages are of people asking questions on Microsoft Connect or the-site-that-shall-not-be-named or something).
omnicognate 5y ago
They're not as good as they were. The win32 docs are a a thing of beauty. I used to actively enjoy writing win32 code, in stark contrast to my experiences with Core Audio which is a similar sort of C API but documented by Apple, which is to say not at all. It is hell on earth. Powershell, though. I don't know how you could even document powershell. It's insane.
- andix 5y ago
  I learned a lot of different programming languages. But I’ve never seen something as cryptic as power shell. Sometimes I write the same script as PS and as bash script. For PS I usually need 3x more characters than for bash. There are some features though that are really useful. But most of the time you won’t know about them when you need them.
  - zaphar 5y ago
    Character count is not generally a good measure of the quality here. I think the biggest issues aren't the verbosity but how complex it can be to express some of the most common operations. Filter is harder than it should be[0]. Same thing for map [0]: https://www.concurrency.com/blog/august-2018/powershell-basics-filtering-and-selecting https://www.concurrency.com/blog/august-2018/powershell-basi...
  - jiggawatts 5y ago
    > Sometimes I write the same script as PS and as bash script. That's your mistake! Don't write bash scripts in PowerShell, and don't write PowerShell scripts in bash. Don't be surprised if the shopkeeper can't understand you, when you're speaking "French" by translating an English sentence word for word. PowerShell is much more readable, terse, and elegant than Bash. It absolutely blows it out of the water... on Windows, where its inputs are the streams of objects that it's designed for. If you're trying to shoehorn text-based streams like in Linux into a PowerShell script, you're going to have a bad time. See this earlier comment I made and the linked comments for some examples of PowerShell-vs-Bash: https://news.ycombinator.com/item?id=23423650 https://news.ycombinator.com/item?id=23423650
    - infamia 5y ago
      PowerShell elegant? Wow. No way. I've written hundreds of thousands of lines of PowerShell on Windows over the years. PowerShell is great for one-liners and very short scripts. It also has many cool hooks into the OS that makes things more comfy. That said, as soon as you need to write a modestly long script or need something remotely performant, you're going to want to reach for the nearest pencil to shove into your ear. I'll take Bash with all its limitations and arcane warts every time. I vastly prefer Python to either Bash or PowerShell for anything serious. A sterling example of PowerShell's inanity is its brain-dead, ivory tower implementation of function return values. Anything that outputs to stdout gets added to the return value object for your function. Forgetting for a moment how non-standard and unexpected this is, consider that it’s impossible to completely silence many, many Windows commands CLI programs and utilities. Even with all the silent flags, output redirection, etc. it is simply impossible to silence stdout. What you end up with is... you just can't ever use return values in functions since it's so unreliable. This, coupled with PowerShell's atrocious performance (it's the worst performing scripting language I've used by far) instantly makes PowerShell a second class language for anything apart from very small scripts. I've never heard anyone call PowerShell “terse” until today. It is currently winning the competition with Java for “Language whose inventor is most likely paid per keystroke”. PowerShell's arguments are extremely verbose and lines tend to become quite long as a result. Disclaimer: I’m a recovering Windows Admin and haven't used PowerShell in a few years. I'm told that none of these problems have been fixed, but I don't know for a fact.
- stdgy 5y ago
  Powershell is so weird to me. It never does what I expect it to do but it’s also full of powerful features. When looked at as a programming/scripting language it feels totally insane and disjointed. I just jump into C# or Python instead of dealing with it, because it just doesn’t make any sense to me as an engineer. But whenever I’m looking up how to manipulate some obscure bit of Windows, a cut and paste powershell one liner always makes an appearance. Does anyone know if there’s any sort of reflective documentation or anything in powershell? Like, is there a way to ask it what arguments exist for a command?
  - kaba0 5y ago
    Get-Help cmd ? But you can even leave out the arguments and it will query for the mandatory ones. Also just FYI, it can fuzzy match on arguments, so you can specify only the first letter, or substring of the whole name. I think from this aspect, it is far superior to the UNIX tools.

by pas 5y ago

Well, PowerShell docs are next to useless. Maybe the other parts are better. But I think this mythos of great docs for proprietary MS stuff is just that, a myth.

fiddlerwoaroof 5y ago

Yeah, I’ve tried a handful of Microsoft products and MSFT’s docs are ok for tutorials, but I’ve often found it hard to find useful reference documentation: e.g. the tutorial bits of Appcenter’s Codepush and UI Testing documentation are ok, but the reference documentation for both is ambiguous and/or incomplete.

radicalbyte 5y ago
With Microsoft, generally the documentation around the edges isn't great. The edges being the "Microsoft condoned solutions and generally anything coming from the Office/Enterprise side. On the Enterprise side they often have fantastic documentation but they have an amazing talent for making it unfindable. It's like they hire an army of noob-level interns who churn out "getting started" articles, with the end result being that you have to dig 5 pages deep into Google result to get meaningful documentation (4 of those pages are of people asking questions on Microsoft Connect or the-site-that-shall-not-be-named or something).

omnicognate 5y ago

They're not as good as they were. The win32 docs are a a thing of beauty. I used to actively enjoy writing win32 code, in stark contrast to my experiences with Core Audio which is a similar sort of C API but documented by Apple, which is to say not at all. It is hell on earth. Powershell, though. I don't know how you could even document powershell. It's insane.

andix 5y ago
I learned a lot of different programming languages. But I’ve never seen something as cryptic as power shell. Sometimes I write the same script as PS and as bash script. For PS I usually need 3x more characters than for bash. There are some features though that are really useful. But most of the time you won’t know about them when you need them.
- zaphar 5y ago
  Character count is not generally a good measure of the quality here. I think the biggest issues aren't the verbosity but how complex it can be to express some of the most common operations. Filter is harder than it should be[0]. Same thing for map [0]: https://www.concurrency.com/blog/august-2018/powershell-basics-filtering-and-selecting https://www.concurrency.com/blog/august-2018/powershell-basi...
- jiggawatts 5y ago
  > Sometimes I write the same script as PS and as bash script. That's your mistake! Don't write bash scripts in PowerShell, and don't write PowerShell scripts in bash. Don't be surprised if the shopkeeper can't understand you, when you're speaking "French" by translating an English sentence word for word. PowerShell is much more readable, terse, and elegant than Bash. It absolutely blows it out of the water... on Windows, where its inputs are the streams of objects that it's designed for. If you're trying to shoehorn text-based streams like in Linux into a PowerShell script, you're going to have a bad time. See this earlier comment I made and the linked comments for some examples of PowerShell-vs-Bash: https://news.ycombinator.com/item?id=23423650 https://news.ycombinator.com/item?id=23423650
  - infamia 5y ago
    PowerShell elegant? Wow. No way. I've written hundreds of thousands of lines of PowerShell on Windows over the years. PowerShell is great for one-liners and very short scripts. It also has many cool hooks into the OS that makes things more comfy. That said, as soon as you need to write a modestly long script or need something remotely performant, you're going to want to reach for the nearest pencil to shove into your ear. I'll take Bash with all its limitations and arcane warts every time. I vastly prefer Python to either Bash or PowerShell for anything serious. A sterling example of PowerShell's inanity is its brain-dead, ivory tower implementation of function return values. Anything that outputs to stdout gets added to the return value object for your function. Forgetting for a moment how non-standard and unexpected this is, consider that it’s impossible to completely silence many, many Windows commands CLI programs and utilities. Even with all the silent flags, output redirection, etc. it is simply impossible to silence stdout. What you end up with is... you just can't ever use return values in functions since it's so unreliable. This, coupled with PowerShell's atrocious performance (it's the worst performing scripting language I've used by far) instantly makes PowerShell a second class language for anything apart from very small scripts. I've never heard anyone call PowerShell “terse” until today. It is currently winning the competition with Java for “Language whose inventor is most likely paid per keystroke”. PowerShell's arguments are extremely verbose and lines tend to become quite long as a result. Disclaimer: I’m a recovering Windows Admin and haven't used PowerShell in a few years. I'm told that none of these problems have been fixed, but I don't know for a fact.
stdgy 5y ago
Powershell is so weird to me. It never does what I expect it to do but it’s also full of powerful features. When looked at as a programming/scripting language it feels totally insane and disjointed. I just jump into C# or Python instead of dealing with it, because it just doesn’t make any sense to me as an engineer. But whenever I’m looking up how to manipulate some obscure bit of Windows, a cut and paste powershell one liner always makes an appearance. Does anyone know if there’s any sort of reflective documentation or anything in powershell? Like, is there a way to ask it what arguments exist for a command?
- kaba0 5y ago
  Get-Help cmd ? But you can even leave out the arguments and it will query for the mandatory ones. Also just FYI, it can fuzzy match on arguments, so you can specify only the first letter, or substring of the whole name. I think from this aspect, it is far superior to the UNIX tools.