Fog Creek Software
Discussion Board




Who writes the documentation for the MSDN APIs

Are the MSFT devs that actualy implement the "Platform SDK API" the same people that actually write the MSDN docs?

Example: CreateWindow()

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/WinUI/WindowsUserInterface/Windowing/Windows/WindowReference/WindowFunctions/CreateWindow.asp

Heston Holtmann
Tuesday, July 22, 2003

I don't know.

The people who write the C#, ADO .NET and .NET Framework docs should be, IMHO, forced to revise the docs.

Jay
Tuesday, July 22, 2003

It varies. My guess would be that the program manager would have written a spec for the function at some point, and a tech writer would have translated the spec to a document, possibly without understanding it, and there would have been six or seven back and forths between the developer, program manager, and tech writer trying to get it right, with varied results, depending on the quality of the aforementioned three people, with the tech writer pretty much taking the lead of driving the process while probably not understanding much of the topic at hand.

I've often found that these help topics are contradictory or specifically lacking in some piece of information that you obviously need to call the function successfully, because the writer was not really a programmer and didn't quite know to ask.

Joel Spolsky
Tuesday, July 22, 2003

By the way, although the documentation for CreateWindow looks abysmal to a novice, once you've been programming on Windows for about 10 years it's really quite readable :)

Joel Spolsky
Tuesday, July 22, 2003

I'm with you on this one, Joel. The CreateWindow help page is very readable to me. :-)

John K.
Tuesday, July 22, 2003

It looks good to me. How could it be better? It has hyperlinks to "overview" and "example" sections...

Christopher Wells
Tuesday, July 22, 2003

By the way, CreateWindow() is to my mind a prime example of attempting to do "OO" in C. You end up with a lot of sort of quasi-overloaded parameters, and a nearly infinite variety of ways in which to combine things to make new things.

It's EXTREMELY intimidating to someone who doesn't know the API VERY well.

Brad Wilson (dotnetguy.techieswithcats.com)
Tuesday, July 22, 2003

I think MSFT's API documentation tends to vary wildly in some spots but overall I feel it is very good.  What exactly is it about CreateWindow()'s docs that we were supposed to be interested in? 

It looks fine to me, and the core Win32/PlatformSDK docs in general are usually great, IMO. 

As was mentioned in an above post, the .NET Framework docs are a bit more troublesome in that they offer far less information than the Win32/PSDK docs and they are overly cluttered by trying to stuff syntax usage of all the different core .NET languages onto one page -- they'd be better off just having completely seperate docs for VB vs C# vs whatever if you ask me, and I'm sure they could create some automated documentation generator that made it so maintaining various versions wouldn't be significantly harder.

Mister Fancypants
Tuesday, July 22, 2003

""By the way, CreateWindow() is to my mind a prime example of attempting to do "OO" in C. You end up with a lot of sort of quasi-overloaded parameters, and a nearly infinite variety of ways in which to combine things to make new things.""

To be fair, CreateWindow and most of the rest of the Win32 API (much of which was inherited from Win16 for that matter) is from a different era.

Microsoft is doing everything it can to push people to the .NET Framework and in my honest opinion the .NET base libs are an OO wet dream in terms of being well designed and very consistent.  Not perfect -- nothing is -- but pretty darn close.

Mister Fancypants
Tuesday, July 22, 2003

I wasn't disparaging the Win32 API. I was merely trying to point out that our transition away from C-style procedural languages into more object-model languages is a great help in productivity.

Brad Wilson (dotnetguy.techieswithcats.com)
Tuesday, July 22, 2003

Ummm I'm not entirely sure about the increase in productivity, certainly not in terms of C++, in C# you're basically down to twiddling properties and overloading the odd event handler or method.

Yes you can produce something, but largely its something that already existed a zillion times already.  All encompassing frameworks can limit as well as liberate.

Simon Lucy
Tuesday, July 22, 2003

I ask because it seems to me that the _best_ person to write the "details" of the API (or interface) documentation is the developer who actualy does the design (and/or) implementation.

It seems that when companies are SMALL.. the dev does everything
  Design, Write, Build, Test, Debug, and Document
I even do the SETUPs for my companies products.

But as the company gets bigger i suspect that this is not the case, or am i wrong?

Heston Holtmann
Tuesday, July 22, 2003

.. but who is writing the SDK Sample applications? Are these
the developers that do the core API ?
Are the SDK samples used as internal tests/unit tests, or are those internal tests a totally different thing ?


IMHO what is good about Microsoft is that there is (always?) some sort of sample in that huge SDK - others don't have that.

Michael Moser
Tuesday, July 22, 2003

I like the .NET docs.  Or at least I think I do.  It might be that I just need them less.

      
Tuesday, July 22, 2003

SDK sample apps are cheap throwaways and were traditionally writtten by junior programmers. Nowadays I think they use offshorers for that.

API documentation is prepared by dedicated documention groups and obviously verified by the program managers, developers and test groups.

.
Tuesday, July 22, 2003

Know those XML tags in C# comments?

http://msdn.microsoft.com/msdnmag/issues/02/06/xmlc/

The tech writers are trying to offload newer API documentation back onto the devs, by letting them write the API comments themselves in the function header. (The C# compiler, csc, can enforce this at compile time by emitting an error if a comment is missing on an exposed API.)

Presumably the idea is to leave the tech writers time to do better overview articles, or more complex sample apps. Results may vary.

Terry B. Barry
Wednesday, July 23, 2003

I remember reading somewhere that all MSDN and distributed samples now have to go through the same code review and security review process as the actual software. The rule is, 'if you wouldn't be happy shipping that sample as actual software, it doesn't get shipped.' MS have found that a lot of developers just take code out of samples and reuse it - and why not?

This came out of the poorly coded samples distributed with IIS 5.x - if enabled, they can be exploited as a back door into the web server. Current security practice recommends turning off those samples (and the MS Baseline Security Analyzer checks for this).

The role of tech writers is generally to translate developer-speak and the specs into documentation usable by outsiders. The specifications probably say exactly how CreateWindow works (e.g. what IPC message(s) to send to CSRSS, how to interpret the response) without really saying what it does - the forest is lost for the trees.

I do agree that sometimes MSDN can be hopeless - you need to know some critical piece of information about how a particular API works when you perform x operation. That's what forums and newsgroups can be useful for.

Raising the ugly spectre of open source, it's true that 'all you need to know is in the source'. However, actually being able to read and understand the source is no substitute for documentation, IMO.

Mike Dimmick
Wednesday, July 23, 2003

By the way, Microsoft includes a handy feedback links on all documentation pages (or at least all .NET pages).  And in my experience, they actually READ the comments & corrections you send them!

So if you find errors or poorly worded text just send them an e-mail, they'll check it out and fix it.  Just make sure you use that feedback link on the page, otherwise your e-mail probably won't reach the right people.

As for the Platform SDK documentation, it's damn near flawless and I don't know why anyone would complain about it.  The .NET docs still have lots of holes, though.

Chris Nahr
Wednesday, July 23, 2003

What I really hate about the MSDN help is the examples. Sometimes they use very simple exemple that never happens in real code because there's more than just one line of execution. Or the opposite : an extreme case that never happens in 99% of cases and they chose that one as an example that is not the real way to use the function.

Application Specialist
Wednesday, July 23, 2003

*  Recent Topics

*  Fog Creek Home