Re: Documentation simply isn't cool.
Hang on while I make a record of that response.
A few years ago, programmer and writer Bernard Meisler argued that coders write bad software because they're bad writers. "Most engineers can't write a single coherent sentence, never mind string together a paragraph," he wrote. So when software engineers write documentation, he reasoned, their incoherent API descriptions …
Hang on while I make a record of that response.
agile =/= no documentation
I use the "Help" menu in Microsoft FrontPage 97. Hasn't let me down yet.
So, this has been around 12 years? Might want to work on their search page ranking.
I recently google'd how to do some 'tricky things' with style sheets [read: I have to fix someone else's bogus b0rked-up style sheets by embedding "style=" within the tags directly to avoid excessive work] and so I've stumbled across the Mozilla dev network pages. They're not bad. Not "super scripty" and load times are pretty reasonable. Reasonably well laid out, though going from HTML section to CSS section involves naviguessing up to the top level and back down again. Still, not bad. MUCH easier on the bandwidth than MSDN ever was!!!
well, until it becomes ad-driven BLOATWARE, but still...
While back I stumbled onto some outdated html stuff on w3schools. googling up some more, I saw a thread with several devs (who seemed to have a clue), stating that they avoided w3schools because they sometimes were wrong and much preferred MDN for mostly being right.
My take on it is that MDN usually goes deeper and I don't have to worry as much about it being wrong 5% of the time. But, yes, w3schools often gets higher ranking on search, doesn't mean I have to follow it.
MDN was for example a big help getting my SSL up to snuff at an html headers and site configuration level - they are thorough, very well explained, and link to a lot of their own explanations as well as pointing to specialized scanner sites. I still had to do a ton of research but they were definitely my key goto.
"So, this has been around 12 years? Might want to work on their search page ranking."
That bit I can agree with. I have to prefix my searches with "MDN" to avoid the noddy sites.
Don't blame Mozilla for you not looking further than the first hit in Google.
They are offing a decent free service, you choose to go for an advert laden one, fine.
The reason MS and Google care is because people like you are writing bad web pages.
And Mozilla is writing good ones.
The reason, why Stack Overflow is such a popular reference for developers, is that you can find many real examples there and not just good English.
Good English gives you a general idea. Which might be enough for some people, when they are already familiar with the code. But when you are doing it for the first time, then you need real examples in the documentation. Or else this documentation doesn't help you much.
English language isn't a programming language. Which means that you lose a lot of details and information, when you translate code into English.
MDN's big strength compared to crap like W3S is that it includes a number of in-depth examples, documentation on inheritance order and how modifiers affect it, and other information that can help both novices and pros track down problems and solve tricky things more efficiently. It's not just the fact that they write English clearly, they also write code clearly. (And yes, they do integrate good stuff from Stack Exchange.)
Unlike MSDN, they aren't written primarily by first-year junior interns and only reviewed by senior developers when they want to, and unlike W3S, they don't just give a barely surface-level overview of with a trivial 3-line example of usage.
A few years back Microsoft tried to lead a multi-
vendorsteward effort at consolidated documentation of 'web', WebPlatform.org. Unfortunately the consolidation started with a straight dump from Microsoft's web documentation. And remember, they didn't get 'web' for a long time. It was lacking, lack-luster and often wrong.
Somehow they got a clue and dumped it onto Github, after declaring the effort 'discontinued' sometime post-2015. That was actually a good illustration that things _are_ getting more real at Microsoft re: 'web'. (Unbelievable but true)
If Microsoft are now linking to MDN for web apis it is only further recognition of bad their own docs were. Another (amazing) instance of getting more real. Cue glaciers in hell...
Is why I still use Firefox to develop on when others swear by chrome. (That and scratchpad/web ide are much better than chromes attempts that I've found). MDN also keeps a damn good record of old standards and what's replaced them which is always good.
Using Chrome to develop doesn't stop you using the docs on MDN.
It doesn't but I've never found chrome tools all that great (in the early days they weren't a scratch on firebug). And I never claimed that using chrome would stop you using MDN, I merely implied that Mozilla tend to be more developer friendly overall so using MDN as a single source of truth is no bad thing.
Mozilla documents the standards and Microsoft adds the exceptions
It's a wiki. If you think you can explain it better, or at least differently - go nuts, there's nothing stopping you.
who's to say MDN are even any good at presenting that material.
Microsoft, did you read the article ? Ok, I admit, Microsoft claiming something else is good means nothing to most techs ... but MDN is really good, I use it a lot when I have webdev to do.
Besides, MDN is a wiki, if you can do any better, be our guest and thanks in advance!
"A helicopter was flying around above Seattle yesterday when an
electrical malfunction disabled all of the aircraft's electronic
navigation and communication equipment. Due to the clouds and haze
the pilot could not determine his position or course to steer to the
airport. The pilot saw a tall building, flew toward it, circled, drew
a handwritten sign and held it in the helicopter's window. The sign
said "WHERE AM I ?" in large letters.
People in the tall building quickly responded to the aircraft, drew a
large sign and held it in a building window. Their sign said, "YOU
ARE IN A HELICOPTER." The pilot smiled, waved, looked at his map and
determine the course to steer to SEATAC (Seattle/Tacoma) airport and
After they were on the ground, the co-pilot asked the pilot how the
"YOU ARE IN A HELICOPTER" sign helped determine their position. The
pilot responded, "I knew that had to be the MICROSOFT building
because they gave me a technically correct but completely useless
Just idly pondering whether there's a subtext hidden in your post (upvoted, incidentally).
Biting the hand that feeds IT © 1998–2018