Web Platform Docs Debuts with Developer Resources

re: Web Platform Docs Debuts with Developer Resources

Nathan — Mon, 15 Oct 2012 12:18:44 GMT

I think this is my personal favorite on MSDN. Lets count the WTFs!

msdn.microsoft.com/.../ms533063%28v=vs.85%29.aspx

snippet 1:

<HTML>

<FORM ACTION="example.microsoft.com/sample.asp"

METHOD="POST">

Enter your name: <INPUT NAME="FName"><BR>

Favorite Ice Cream Flavor:

<OPTION VALUE="Chocolate">Chocolate

<OPTION VALUE="Strawberry">Strawberry

<OPTION VALUE="Vanilla" SELECTED>Vanilla

</SELECT>

</FORM>

</HTML>

1 - no doctype

2 - no head

3 - no body

4 - uppercase tags

5 - uppercase attributes

6 - self closing tags not closed

7 - quotes missing on attributes

8 - no closing option tags

9 - no closing p tag

10 - boolean attribute not properly referenced

but it gets better, here is snippet 2:

<input name=subject type=hidden

value="Widget%20Product%20Information%20Request">

Enter your full mailing address<BR>

<input type=submit value="Send Request"

</form>

11 - what is a "TextArea" tag? and why doesn't it have a matching closing tag?

12 - poor submit tag not only is missing a closing slash, but also a closing angle bracket

13 - still have upper case tags

14 - still have upper case attributes (and values!)

All in all the quality of examples (as well as detail & accuracy) of MSDN documentation is beyond pathetic. I seriously hope that absolutely **NONE** of this content gets submitted to the Web Platform Documentation site.

re: Web Platform Docs Debuts with Developer Resources

Marc — Fri, 12 Oct 2012 18:06:41 GMT

Just kidding. Actually MSDN documentation is first class. Since I am not a developer nor a professional, so I don't know anything about it.

re: Web Platform Docs Debuts with Developer Resources

aaWish for the again — Fri, 12 Oct 2012 00:42:45 GMT

Release the Internet Explorer 10 for Windows 7!

Please hurry.

re: Web Platform Docs Debuts with Developer Resources

Marc — Fri, 12 Oct 2012 00:37:39 GMT

Glad to see that MSDN documentation failures are making it to the surface! Even if Microsoft doesn't contribute them they can at least spend some time to re-vamp them correct all the errors and make them at least useful for once!

Whenever I see a fellow developer (that isn't trying to solve an IE-only bug) on MSDN I've had to stop and make sure they were only reading it for humor not for actual facts examples and advice.

re: Web Platform Docs Debuts with Developer Resources

Tom P. — Thu, 11 Oct 2012 16:23:11 GMT

@Brian, @David

I am working for an organization which is working closely with RedHat at NYC. But admittedly, MSDN documentation is one of the greatest repository for developers. The WORST examples Brain has filtered from over 10,000,000 pages doesn't invalidate/void the relaibility of MSDN.

Now tell your employer Google to come up with something really tangible examples and tools to troll against Microsoft.

re: Web Platform Docs Debuts with Developer Resources

Marblo — Thu, 11 Oct 2012 13:24:06 GMT

How about this mess for the form element documentation!

<HTML>

Enter your name: <INPUT NAME="FName"><BR>

Favorite Ice Cream Flavor:

<OPTION VALUE="Chocolate">Chocolate

<OPTION VALUE="Strawberry">Strawberry

<OPTION VALUE="Vanilla" SELECTED>Vanilla

</SELECT>

</FORM>

</HTML>

All upper case tags! (Looks like 1996!)

No head or body tags

Input without type attributes!

Why are all the closing tags and slashes missing!

Such horrible examples on MSDN! Please do not submit any of these bad examples to the new site! Please!

re: Web Platform Docs Debuts with Developer Resources

Douglas — Wed, 10 Oct 2012 10:17:29 GMT

The part I hate most about MSDN documentation is the complete lack of consistency which is so bad when trying to teach new developers good habits!

Check out this example code they have for the input tag:

msdn.microsoft.com/.../ms535260(v=vs.85).aspx

<P>Password</P>

<p>Color</p>

<br><input type="radio" name="control3" value="0" checked>Red

<input type="radio" name="control3" value="1">Green

<input type="radio" name="control3" value="2">Blue

<p>Comments</p>

<p><input name="control5" type=checkbox checked>Send receipt</p>

</form>

1) some tags are in uppercase, why?!

2) some attribute values are in uppercase, why?!

3) some attribute values are not quoted, why?!

4) self closing tags like br and input are not closed, why?!

5) invalid size attribute values are supplied, why?!

6) Boolean attributes are not properly qualified, why?!

7) why are all the fieldnames named so anonymously when their purpose is fully known?

Why even bother posting a sample if you're not going to put a descent effort into it?

re: Web Platform Docs Debuts with Developer Resources

Arieta — Tue, 09 Oct 2012 23:36:11 GMT

@Olivier: Now run the validator on google.com or mozilla.com ;)

re: Web Platform Docs Debuts with Developer Resources

zoe — Tue, 09 Oct 2012 19:09:30 GMT

MSDN samples are brutal!

how can a click() sample be so bad?

msdn.microsoft.com/.../ms536363%28v=vs.85%29.aspx

<HTML>

<HEAD>

function simclick1()

{

chk1.focus(); //focus is explicitly set

chk1.click();

}

function simclick2()

{

chk1.click();

}

</SCRIPT>

alert("check box is in focus!");

</SCRIPT>

</HEAD>

<BODY>

<P STYLE="font-family:sans-serif;font-weight:bold">DEMO: USING CLICK METHOD

DOES NOT SET FOCUS<P>

<LI>Both these buttons apply the click method to the check box. </LI>

<LI>An alert has been set to fire when the check box is put into focus.

</UL>

</PLI>

<br>

<BUTTON onclick="simclick1()">This button <B>applies the focus method</B> to

check box</BUTTON>

<br><BUTTON onclick="simclick2()">This button <B>does not apply the focus

method</B> to check box</BUTTON>

<br>

</BODY>

</HTML>

what is a PLI element? why are some tags UPPER CASE and some lower case and some attributes are UPPER CASE some are lower case and some are Sentence case!

I've got a 10 year old that could write cleaner code than this with his eyes closed!

re: Web Platform Docs Debuts with Developer Resources

Brian — Tue, 09 Oct 2012 18:37:06 GMT

@Eng/ Ronald MSDN documentation does have lots of issues you can look up pretty much anything to find bad examples. Case in point a random article about appendChild() a fairly modern API:

msdn.microsoft.com/.../ms535934%28v=vs.85%29.aspx

Lets start the complaint list:

1 - code sample is using Hungarian Notation (oDiv). This sets a VERY BAD example for modern web code snippets

2 - script tag outside the body AND NOT inside a head tag

3 - document.createElement() used with UPPER CASE tag names

4 - no quotes on the ul id attribute

5 - odd spacing on all attributes on the input tag. e.g. should be: attribute="value"

(we are trying to teach developers best practices here!)

but it gets worse... lets try something that has worked for over 15 years... how about document.write:

msdn.microsoft.com/.../ms536782%28v=vs.85%29.aspx

Lets look at the example code.... (here's a copy of it)

IHTMLDocument2 *document; // Declared earlier in the code

BSTR bstr = SysAllocString(OLESTR("Written by IHTMLDocument2::write()."));

// Creates a new one-dimensional array

SAFEARRAY *psaStrings = SafeArrayCreateVector(VT_VARIANT, 0, 1);

if (psaStrings == NULL) {

goto cleanup;

}

VARIANT *param;

HRESULT hr = SafeArrayAccessData(psaStrings, (LPVOID*)&param);

param->vt = VT_BSTR;

param->bstrVal = bstr;

hr = SafeArrayUnaccessData(psaStrings);

hr = document->write(psaStrings);

cleanup:

// SafeArrayDestroy calls SysFreeString for each BSTR

if (psaStrings != NULL) {

SafeArrayDestroy(psaStrings);

}

I'm sorry... what planet are you on? which part of this has **ANYTHING** to do with JavaScript? SafeArrayCreateVector()? come again... SafeArrayUnaccessData()? who writes these mangled APIs? SafeArrayDestroy calls SysFreeString for each BSTR? Can I buy a vowel?

There are literally dozens of issues like this in Microsoft Documentation - and we therefore are MAJORLY PARANOID that Microsoft is "donating" any code/documentation to an open project.

3rd time's a charm?... nope!

document.close();

msdn.microsoft.com/.../ms536369%28v=vs.85%29.aspx

Notice how the description is correct: "Closes an output stream and forces the sent data to display."

But the example is completely incorrect, showing code that applies to the "window.close();" API call, NOT the "document.close();" API call which does completely different things.

Long story short... MSDN Documentation is some of the WORST documentation I have ever seen and I fully agree with David in my hopes that the BAD stuff is NEVER ported to the new Web Platform site.