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 …

  1. This post has been deleted by its author

    1. Anonymous Coward
      Happy

      Re: Documentation simply isn't cool.

      Hang on while I make a record of that response.

    2. Baldrickk

      Re: Documentation simply isn't cool.

      agile =/= no documentation

  2. hellwig

    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.

    1. bombastic bob 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...

    2. JLV

      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.

    3. Brewster's Angle Grinder 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.

    4. teknopaul

      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.

  3. Nick Z

    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.

    1. foxyshadis

      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.

  4. Notas Badoff

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

  5. Sgt_Oddball

    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.

    1. Brewster's Angle Grinder Silver badge

      Re: this

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

      1. Sgt_Oddball

        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.

  6. Sven Coenye
    Coat

    Makes sense

    Mozilla documents the standards and Microsoft adds the exceptions

  7. This post has been deleted by its author

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

    2. Hans 1
      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. Anonymous Coward
    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."

    1. Ken Moorhouse Silver badge

      Re: Due to the clouds and haze...

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

      1. Anonymous Coward
        Anonymous Coward

        Re: Due to the clouds and haze...

        Hazy clouds involved in catastrophic failure?

        That would never happen…

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

Other stories you might like