back to article Microsoft concedes to Mozilla: Redmond will point web API docs at Moz Dev Network

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 …

This post has been deleted by its author

Silver badge
Happy

Re: Documentation simply isn't cool.

Hang on while I make a record of that response.

10
0
Silver badge

Re: Documentation simply isn't cool.

agile =/= no documentation

0
0
Silver badge

MDN? Never heard of it.

I use the "Help" menu in Microsoft FrontPage 97. Hasn't let me down yet.

But seriously, never heard of it. Not that I'm a web developer, but when I have HTML, CSS, or JavaScript questions, Google usually serves up links from W3schools or StackExchange (depending on how restricted my question is).

So, this has been around 12 years? Might want to work on their search page ranking.

12
0
Silver badge
Devil

Re: MDN? Never heard of it.

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...

8
1
JLV
Silver badge

Re: MDN? Never heard of it.

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.

5
0
Silver badge

Re: MDN? Never heard of it.

"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.

5
0
Bronze badge

Re: MDN? Never heard of it.

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.

5
0

Without examples, good English doesn't tell you much

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.

7
0

Re: Without examples, good English doesn't tell you much

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.

1
0
Silver badge

Start from 'working'

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...

11
0
Silver badge

this

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.

8
1
Silver badge

Re: this

Using Chrome to develop doesn't stop you using the docs on MDN.

3
0
Silver badge

Re: this

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.

1
0
Coat

Makes sense

Mozilla documents the standards and Microsoft adds the exceptions

12
0

This post has been deleted by its author

Silver badge

It's a wiki. If you think you can explain it better, or at least differently - go nuts, there's nothing stopping you.

8
0
Silver badge
Holmes

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!

8
1
Anonymous Coward

Old joke about Microsoft, documentation and helicopters ...

"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

landed safely.

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

answer."

21
0
Silver badge

Re: Due to the clouds and haze...

Just idly pondering whether there's a subtext hidden in your post (upvoted, incidentally).

2
0
Anonymous Coward

Re: Due to the clouds and haze...

Hazy clouds involved in catastrophic failure?

That would never happen…

1
0

POST COMMENT House rules

Not a member of The Register? Create a new account here.

  • Enter your comment

  • Add an icon

Anonymous cowards cannot choose their icon

Forums

Biting the hand that feeds IT © 1998–2018