It seems to be the general rule of thumb that, when you want to google for an oracle error message, then exclusion of both oracle documentation site, and developer forums is your first criteria on the search bar. Same applies to Microsoft (large parts of MSDN), and now Amazon Web Services documentation (at least some parts of it).
That's the reason StackOverflow works - it really solves programmer's problems, instead of the strange dialects of English and style that flourish on MS and Oracle and Java docs.
I'm not sure why the hate against MSDN - at least for .NET, I found the documentation to be one of the best in the business -even a decade ago. I'd only put Go's docs ahead in terms of helpfulness. I cut my teeth writing .NET code, then switched to Java writing apps on Android - the step down in doc quality was quite significant.
MSDN isn't terrible, but for answers.microsoft.com 90% of questions are some outsourced foreign support rep telling the user to run sfc /scannow and not looking into the issue any further. Which makes it a huge pain for sysadmin type stuff, their developer documentation is much better.
answers.microsoft.com accepted answers are mostly accepted by the poor foreign support rep after OP have left disappointed. It is somewhat similar in quality to yahoo answers. Microsoft should be ashamed this pile of useless bits is public.
Let me make sure I understand the problem you're having trouble getting answers from answers.microsoft.com, is that correct?
Please open the site answers.microsoft.com in Microsoft Edge web browser and once the page loads, look for answers there. This should solve the issue.
Can you also please run the windows memory diagnostic tool and paste in the output in a reply to this message? Once you have done that, please open your computer and make sure that your CPU is firmly seated in its socket. That will be required to help further.
If this has helped solve the problem finding answers on answers.microsoft.com please mark it as correct.
> outsourced foreign support rep telling the user to run sfc /scannow
Sysadmin story. Recently I had a really strange problem after a disk migration - defrag.exe simply would not run no matter what (I needed it to TRIM the SSD), it just quits without any messages, as if it's /bin/false. GUI had the same problem.
The first search result was a thread at answers.microsoft.com, they give the same canned "sfc /scannow, dism /restorehealth, chkdsk /f" response. But OP finally solved the problem on their own, the "Optimize Drives" service was somehow been stopped, restarting it solved the problem. I tried it, it didn't work. Having no options, I decided to give the seemingly useless solution a shot (why did I bother to try? This was after a disk migration, I felt filesystem corruption could be real). It finally worked after "chkdsk /f"...
I was genuinely impressed. It was the first time ever that it actually fixed a real problem for me. Presumably defrag.exe detected a filesystem anomaly and refused to run.
> defrag.exe simply would not run no matter what (I needed it to TRIM the SSD)
Would be interested in the logic here, given that it runs counter to what I thought was extremely obvious advice by now.
Defrag generates writes to rearrange blocks in the _virtual_ view of storage visible to the OS, but even after defragmentation, the _physical_ placement is totally outside the control of anything except the firmware. If after defragmentation a file's blocks are arranged (0, 1, 2, 3) in the OS-visible view, in flash are still very likely to to be arranged (412, 77, 1, 12341, 5) etc. All you can do is let it know that some range of sectors is not used, which is what TRIM enables, and that does not require defragmentation upfront.
> All you can do is let it know that some range of sectors is not used, which is what TRIM enables, and that does not require defragmentation upfront.
This is exactly what defrag.exe does on an SSD today. Since Windows 10 (or 8?), instead of doing a "real" defrag, defrag.exe also has an option to issue TRIM commands to unused blocks on an SSD. In other words, it works like fstrim(1). The time has changed and you must have missed the update. I suggest keeping your knowledge up-to-date before delivering a lecture on disk defragmentation on a forum where everyone should've known better.
> /d Perform traditional defrag (this is the default).
> /l Perform retrim on the specified volumes.
> /o Perform the proper optimization for each media type.
Since I migrated the hard disk using a block-level copy via "dd", it's a good idea to manually TRIM the disk afterwards to inform the controller about the unused blocks in the new filesystem for proper wear leveling (to the controller, the block-level copy looks like a single large file).
And before another one gives me another lecture: No, I did not corrupt the filesystem because I made the mistake of copying the disk while Windows was still in Fast Startup mode. It was probably ntfsresize(8), to be fair, the corruption was extremely minor.
Thanks for the excellent explanation, but the attitude and needless personalization was unnecessary. This functionality was previously available via the Optimize-Volume cmdlet, I guess it makes sense the defragmenter was updated with similar functionality to account for the typical Windows user.
Yeah that site is terrible. Spent a few days digging for solutions to fix an issue, always ended up back on that site. Always same old useless information.
I had to go to like page 10 of Google results to find some random sysadmin's blog which looked like it came straight out of 2005 and guess what? Problem is explained clearly, steps to fix it are laid out, sorted and wish I found the website 2 days earlier.
I don’t work with Microsoft stuff as much anymore, but my big beefs with Microsoft product documentation are:
- It is was often unclear what version of the “thing” was in scope. An article from product version X will reference X-1 documention.
- Microsoft will gaslight you. If you interact with them on a significant issue, you need to snapshot their product docs. I’ve worked with Premier on issues when pushing products to the edge of their limits, and the product group will edit the product specs in near real-time.
Microsoft is a complex and big entity. While most of it is doing a bad job whatever it is, some parts are quite good. In particular now that the C# stack is fully open, it's very easy to report a bug (on GitHub) and developers are reactive from my experience (submitted a bug impacting the dotnet SDK).
That issue left a sour taste in my mouth. As a customer, I don’t really need to be in the middle of corporate politics, I have my own poisonous politics to deal with!
I share it because many folks can’t conceive that sort of thing being possible.
I found the same. C# being on GitHub combined with the Microsoft documentation has made working with it a breeze. If I ever have any doubt, I just step into the code itself and figure it out.
MSDN and the whole ecosystem around it is a gem. MSFT isn't great at some (or even many) things but I've always felt MSFT really put a lot of effort into developer experience. I don't miss much about moving away from the MSFT orbit except for MSDN and their development tooling. I kind of got some of it back with Visual Studio Code but I still really miss the Visual Studio level of experience.
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.
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.
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?
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.
> 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.
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.
An observation I've made over decades of development in dozens of languages on many platforms is that humans often confuse frequency for speed. They assume that because they are making "many actions per unit time" that they are getting to their solution goal faster.
This is most obviously noticeable (to me at least), when debating ergonomics with people that prefer UNIX platforms, especially bash and text-based configurations. There was a study that showed that an action like moving a mouse to select a file feels slow because there's one slow movement, but selecting the file through typing at a console is perceived to be faster because there are many keystrokes in quick succession. People report that they prefer the latter for "the speed" even if it's an order of magnitude slower than the mouse if measured with a stopwatch.
The terse two-character commands of the UNIX world were an optimisation for teletype. As in a literal typewriter banging away on paper, at a rate of something like 10-30 cps. Modern (four-decade-old!) computers have tab complete, which makes this largely irrelevant.
Verbose commands are an enabler. They enable novice users to read scripts, instead of only masters being able to write them. Long, systematically and consistently named commands enable discovery through wildcard searches.
You cannot now -- nor ever will be able to -- do something like this in the Bash world:
Get-Command Get-Az*Disk*
That's not an option because Bash doesn't actually follow the UNIX philosophy: it's not composable, it's not orthogonal, it's not designed, it's not self-consistent, etc...
It's a clever hack around byte streams that people have slowly built up over decades, evolving over time haphazardly. There was an 'sh' for example!
PS: You talk about using Python instead of scripting languages, which is actually a fine choice that I won't argue with. But have you considered writing "heavyweight" PowerShell modules in C#? As in, a proper DLL module? It's mindblowing how productive it is compared to trying to write a command line tool in C/C++, or any other language for that matter. Automatic input validation, input parameter name tab-complete, pipeline handling, all wired up with a handful of attributes...
> Verbose commands are an enabler. They enable novice users to read scripts, instead of only masters being able to write them. Long, systematically and consistently named commands enable discovery through wildcard searches.
For short scripts, this works great and improves discoverability for newcomers. This is the siren's song of PowerShell. However, the long commands and particularly the often unneeded/overly verbose parameters frequently creates a wall of text. This really hurts readability for everyone in all but the shortest scripts. Additionally, this wall-of-text that is all to common in PowerShell scripts is very intimidating to newcomers.
Regarding Tab completion in PowerShell, it frequently isn't terribly helpful. To work yourself up to something like Get-ItemPropertyValue is quite an incantation to remember, while being worse than a lot of bash ergonomics.
> have you considered writing "heavyweight" PowerShell modules in C#?
That is an interesting approach and would make life more bearable in MS-only shops. However, I can do the same thing with Python, which is superior to PS in so many ways and doesn't suffer any huge, glaring flaws (as PS does).
The performance problems, at least, have had some TLC applied to them and are much better in PowerShell core (the one that goes by pwsh), to the point that I don't hate using PowerShell interactively now.
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
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.
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).
Azure and Powershell docs leave a lot to be desired. A lot of the time parameters are vaguely documented, return values completely undocumented. You have to inspect the object returned by a lot of things to get to understand what members and methods it has, and what they mean.
Examples illustrating what formats it expects inputs in? Forget it.
I assume you have not encountered SharePoint. The SharePoint documentation I could get my hands on - even in books I paid for - was so bad it was like I was living inside some David Lynch interpretation of Ancient Greek myths of divine punishments unleashed upon the worst sinners.
More than once, the "solution" to my problem was a blog post by a SharePoint consultant from India describing some undocumented flag to pass to some obscure command, "but of course, you should never do this on a production system". (I bear no ill will towards Indian SharePoint consultants, to be clear. I just find it really creepy they seem to enjoy this kind of torment.)
PowerShell is easy to debug though. So I never have a problem with that. I generally program in it without ever looking at any documentation. I just don't need it.
Just get-help -full/get-member everything or export-clixml it. But maybe I've done it for too long, so I don't see the weaknesses anymore.
The actual MSDN docs sections are uniformly reasonable in my experience, but some galaxy brains decided to nest at least 2 (if not 3?) user support forums (think "my printer is broken") under the microsoft.com domain. Searching their docs usually requires a bunch of excludes
Microsofts documentation is a mixed bag, but mostly rather good, if you know how to read it.
An example of a place where it's bad is the Python API for Azure. I needed to call some service, I forget which, and everything was clearly just translated from C#. There's a function which takes a string as an input, except it doesn't, it takes one of three string, neither of which is mentioned. I assume that in C# it's an enum, and Visual Studio will just list the option for you.
> Microsofts documentation is a mixed bag, but mostly rather good, if you know how to read it.
“if you know how to read it” is...not a ringing endorsement of documentation. But, its true that MS documentation is less likely to be wrong once you understand what it is trying to say than, say, Amazon's (though have glaring omissions or things concealed by opaque organization is quite common.)
While I'm sure the complaints are valid (or was in the MSDN days) I believe Microsoft is putting a lot of effort behind these pages. You can provide feedback on pages that will result in a GitHub issue being created. You can even make pull requests.
While it's possible to provide feedback not all areas seem to process this feedback in a timely manner which of course is frustrating. However, the good parts (like .NET) are very good.
MSDN was great, Docs is not. There are still lots of inexplicable errors from the migration of content, and they seem content to outsource the labour of finding and fixing them --- errors they themselves created --- to the "community".
I might have been unfair on MSDN, as my experience in the past was really bad. I work with non-MS tech quite a bit, not sure if being deep in the MS-ecosystem helps in grokking the docs.. But I found it uniformly bad across : MS-SQL, Visual Basic, Asp.Net etc.
I think my issue might be more with the English style. But why does SO work right-away for me, while other these other developer portals don't. Part of the flaw maybe lies with me - maybe these portals (like MSDN) need in-depth, patient reading (guilty here). SO on the other hand, is way quicker in helping to solve issues. Over the years though, I've had enough bad experiences ..
Someone should do a compare between SO and non-SO. Take a sample, discrete (if such a thing exists in software issues) issue, and see how both help to solve. The layout of the page, the noise, and finally the curated/voted answer all contribute. And factor in the fact that SO answers are written by a diverse group of people, many of them non-English speaking.
Call it hate, but regardless, Oracle product docs - when you're in a bind are the bottom of the pit.
As far as OEM notes go ms is probably among the best but it’s not saying a lot. I find that most MS notes rarely explain the how very well if at all. They usually just explain the what. Sometimes that is enough, but usually I want to see examples of how to use code to perform a task. For me at least seeing examples of real world use helps infinitely more than here is an object. Here are its public methods. Here are its public fields and properties.
Stack Overflow excels at showing implementation examples which, while the best way is not always highly rated, at least shows a way. When I was more junior I would sometimes take SO answers verbatim but I think now it at least gives me something to think about improving.
“// handle errors here”
“// don’t do this in real code”
Because a list of errors that could occur and a comprehensive list of what is recoverable (and how) vs what should abort is not useful at all in developer documentation…
Just a note that Android Java is not JavaTM, it is just some bastard son of it. I think java has quite a good API documentation, it’s just that google results are usually from java 8 or even earlier versions.
I’m currently taking my first foray into the world of MS applications for work. Have to write something that interacts with an EWS server and I’ve been… overwhelmed with not only the disorganization of their docs, but also the super strong push to do everything in C# instead of just telling me which SOAP (yes that soap) parameters/documents to use for certain actions. If anyone here wants to defend MS and tell me I’m horribly wrong and point me to some fantastic docs somewhere I would be so delighted to be proven wrong.
Yes, pretty much everything is like that: explained in terms of their web services wrapper, not the actual messages sent on the wire. And if you want to log the SOAP messages going back & forth, you have to implement a weird listener class to get them. Microsoft came late to TCP/IP and the web because of their contempt for open, text-based network protocols, and you can still sense it in their products. For instance the C# web client is able to upload mime-encoded files, but the form data name must be `file`. It can't be `photo`. Let alone `photo1` in the same request as `photo2` or a bunch of photos named `user[photos][]`. And you should try reading the Stack Overflow answers for making Powershell print a raw HTTP conversation the way `curl -v` can.
On the other hand, if you do understand the underlying network protocols and can read them (and find ways to view what is happening), it is like a super power.
A lot of times the people writing the code & designing the APIs for the complex parts of AWS, Java, .NET, Spanner, etc... are highly-technical and not exactly highly articulate.
And even the ones that are highly articulate usually have trouble figuring out who exactly their audience is and what their audience knows and to what degree they need to explain things.
And even the select few programmers who are good at this, run into another set of problems. The language they use amongst themselves is usually highly technical (because it reduces confusion and speeds up communication). However, many of the readers of the documentation aren't going to understand a lot of these terms or concepts. The language needs dumbed down.
Because this is time consuming and requires a lot of thought - the documentation is usually written by technical writers. While these people are usually good at figuring out the audience and how best to communicate with the audience - they have their own unique way of writing (for clarity) that usually causes the documentation they produce to feel non-concise and sometimes not even clear.
After reading the page - I only have the vaguest idea of what it actually does and I have almost no idea when I should use it and when I shouldn't or how it actually works (which, tbf, probably isn't important at this stage).
In my experience both Oracle and Microsoft documentation is usually good to excellent,I actually want google to search specifically on ms docs site most of the time. I do find AWS docs to be lengthy and incomprehensible.
StackOverflow is mostly useful to quickly (and often dirtly) solve issues that are burning now, without getting deeper understanding of the subject. This isn't universally true, some answers are exceptionally good.
Honestly I wouldn't mind the MSDN documentation so much or the Microsoft forums if it didn't feel like it was constantly doing this super tedious redirection hot potato because of their SSO Microsoft live account bull crap.
The aws docs aren’t concise, but they have a lot of good information in them if you want to go in depth. I learned a lot back when I was an intern by reading them
Iirc, the postgres docs were also good reading in a similar way: not concise, but a lot of good information
So spoiled by Rust now when using one of these "documented" APIs.
* Rust's examples work, because the default behaviour of Rust's automated testing is to test your documented examples (as well as any unit tests you wrote), so, it's actually more effort to write examples that don't work. If you're too lazy for that, you're going to not write any examples, so then I at least know I'm in uncharted territory.
* The relevant Rust source code is linked. Mostly. Rust's source links don't chase macros, so it's conceivable your link tells you that foo(X) is just the result of the macro make_thing!(foo,X) and you need to chase how make_thing!() is defined which is annoying. But 99% of the time you discover immediately what's actually going on.
This week I would say about half of my time was spent fighting with the C# library for talking to the Microsoft Graph API. Both of which are, in theory, "documented" and yet I repeatedly ended up cribbing from Stack Overflow answers or, after beating my head against a wall, pasting URLs (which I already know will go stale in a year or two) and Microsoft's uselessly bland explanations for the obviously broken stuff as the excuse for why we can't do things you would obviously anticipate being possible.
Today I particularly liked: There are five documented ways to make an educationClass. Most of them simply don't work (unanswered Issues on github), and the error responses for these methods are undocumented and lead nowhere. But one of them does work. However the C# library drops the output of the API call for that method on the floor, presumably because coping with this case was hard, and so the best option (as a Stackoverflow post explains) is to reach inside the library, dredge out the HTTP request it's about to do, and perform that request yourself, then do all the heavy lifting they couldn't be bothered to do with the HTTP response to get what you actually wanted (including a polling loop because apparently nothing after the 1980s happened for Microsoft).
However, in the months since that Stackoverflow post was written, the C# library API has changed, enough that the example code wouldn't even build.
The change is undocumented (of course) and involves an enumeration (also undocumented) which was auto-generated for some reason. This feels like somebody was hoping it wouldn't matter if they changed it, and that somebody was wrong. But if they'd been forced to document it then maybe they'd have either decided it wasn't worth it (still works as before) or I'd have saved ten minutes guessing how the API now works.
But now it's the weekend and I'm going to write Rust.
A thing that helps with Rust, in my opinion, is that the language is statically typed and people mostly write functions. That makes it easy to glue the pieces together in my head. So even if the documentation isn't great, I can find a way to do what I want.
There's still lots of polymorphism in Rust. Take for example the way reqwest handles HTTP headers. Reqwest cares that it's technically possible (albeit a bad idea) to write arbitrary bytes into an HTTP header name even though those bytes are ASCII case crushed. This being understood, and Rust's strings necessarily being UTF-8 and not arbitrary bytes, a header's name might not be a string in Rust (though of course the vast majority are) and so Reqwest carries around a whole marker type for things-that-might-be-plausible-header-names, knowing that all any non-bad-guys will care about is a few simple ASCII strings but needing to correctly handle much more.
The two obvious things work, if you say the name of a header, you get that header, and there are constants like HOST defined for the most common headers to avoid typos, but you can do crazy stuff, and importantly if a hostile peer sends you crazy stuff Reqwest promises to cope.
Maybe it's that Rust's polymorphism is more explicit through Traits.
If Pigeon, Duck and Emu are all Birds, and further more Animals in C++ it's unclear what exactly this Bird superclass does for me, still less Animal or when I, knowing I have a Pigeon here, should consult the documentation for Bird and/or Animal rather than or in addition to that for Pigeon.
Whereas not only does the Emu not implement Fly, I can feel comfortable guessing that the code implementing Fly generically or for my Pigeon is unlikely to be related to my problem that this Pigeon says "quack" and I should instead look closely at the AnimalSound trait, given away by the fact I had to explicitly name that trait to get the "quack" noise from the pigeon.
That's the reason StackOverflow works - it really solves programmer's problems, instead of the strange dialects of English and style that flourish on MS and Oracle and Java docs.