Why I Don’t Like MSDN
OK, the title was an overreach. I don’t like their formatting.
To catch everyone up, MSDN (Microsoft Developer Network) is Microsoft’s massive online API, getting starteds, and everything coding-related repository. Don’t get me wrong. It’s an outstanding resource, more so since it’s free. But it’s not exempted from criticism. In fact, every page asks me if I like it.
I disagree with the API documentation formatting. To catch everyone up, API (application programming interface) is the list of calls for an application. It’s a sort of a dictionary for programming. The call components are explained in detail, such as the parameters, return values, caveats, warnings, sample code, things that aren’t obvious, and things you need to know about the call. It should be the single source of all truth for that call. However, the level of detail is subject to debate, and is a constant source of arguments within the programming world. I’m not going to talk about that here, but know that most of those conversations end with the writers saying something like “Oh, we didn’t have enough time.” Everyone understands that. But I digress.
The formatting is about how and where they place that information on the page. Now that we’re all caught up, I need to admit I had been part of the problem. I was at Microsoft. That wasn’t the problem. I was an API documentation writer, and I toed the line. That was the problem. That standard, back then at least, was the way MSDN did things. It was the 800-pound gorilla as it were. That effort was led by the Visual Studio group. Microsoft insiders will tell you that officially there was not a single standard for those kinds of things, and that each group was free to use their own standard. In reality, you had the freedom up to the time you used that freedom. This Microsoft insider will tell you that there was enormous pressure to conform to the MSDN way of doing things. As a documentation manager in the Evolving Technologies group, I was able to break from the MSDN format, although it took quite a lot of convincing of my management.
What is it about their formatting that annoys me? To answer that, understand that I maintain three truths about writing for developers.
1. They’re lazy. They either only want to do things once, or they want to use the least amount of effort in doing it at all.
2. Put the most important information first. Why make them hunt for information? This points back to the first item.
3. You’re only a newbie once. The documentation has to be everything to all users, but they only read it for the first time once. After that, they come back looking for something specific. That means don’t make them wade through a lot of newbie overviews. This points back to the first item.
Notice a pattern? The beauty of this approach is that all three are really the same thing. They’re lazy, so save them time and put the most likely used information at the top of the page, and make copy and paste easy.
Doing it my way
The following compares the documentation for the call GetFiles(). This is a Windows-based call that returns a list of files in a directory. To be fair, there are several variants, but we’re just looking at the most simple one. Consider listing documentation pieces in the following order:
The call name. Make this big heading 1.
GetFiles(string)
A brief one-line description of the call. Something like “This call does X.” This has a high lazy factor, exactly the sort of thing we’re going for. In one sentence they can decide if this is the right call. If not, they move on. In either case, they will love you for saving them time.
Returns the names of files (including their paths) in the specified directory.
A practical code sample. This is one line of code they can copy, paste, and move on. Honestly, if I thought I could write API documentation using only samples, I would. Examples are all they want. Except for the newbies, they come to get something to copy, see which parameters there are, and the format of the parameters. Having examples of the parameter format is perhaps the single most important factor. Really, this alone can save them a lot time. To make things easier, you don’t have to list all the parameters and their variations, just pick one or two most common cases. Never mind that the parameters aren’t actual values; that would be a good trick. Developers know to change the values to what they need.
string[] fileEntries = Directory.GetFiles(“C:\myFiles\moreMyFiles”)
Everything else. Put the rest of the documentation here. This includes the complete parameter list, notes, enums, and overviews. If they want something detailed, they understand they’ll have to find it.
A comprehensive code sample. Who says there has to only one sample? The practical example listed earlier is one line of code for that call only. The comprehensive example, is a working scenario for that call. It’s about a common case for the call, and includes the lead into it, setting up parameters or other required settings, making the call, getting the results, and applying the results. We get to see Figure 2: GitFiles() example in a good light.
Doing it their way
This continues comparing the API documentation for the GitFiles() call. That’s the complete page, and they may change from time to time. For now, see See Figure 1: GetFiles().
The first two sections are right: The call name and the one-line description.
Their next section is the call’s signature. While it’s factually correct and needed on the page, it’s not needed there. Developers can use the signature to write their call, but it’s just too much work for them. This violates our lazy principle. They would have to modify seven things (italics are deletes, and the bold are the additions):
public static string[] fileEntries= Directory.GetFiles (string Path”c:\folder1”);
In contrast, in my earlier example, they would have to modify only one thing:
string[] fileEntries = Directory.GetFiles(“C:\myFiles\moreMyFiles”)
The parameters and return sections are good. An example of a return value would be good, just to be clear ahead of time what to expect.
I take exception to the Exception section. Let’s be honest. No one reads these. Put them at the bottom, certainly not in the middle.
Their example is a very good, comprehensive section. It follows a logical order, shows the preparation, uses GetFiles(), and includes error handling.
Where this falls short is if the reader wants only to copy and paste the call itself. See Figure 2: GitFiles() example, but now in a bad light. Try to find the line that makes the call. I’ll wait. Even if you found it quickly, it took an effort and broke the lazy principle again. That’s at least three times now. Remember, the user just wants to copy the call.
- They wasted time on the signature thinking how much work that would take.
- They went looking for the example, probably expecting a short one.
- They waded through code looking for the call itself.
In my case, the user already found it, copied and pasted it, modified it, is continuing on their way, and is enjoying the respect and admiration of their coworkers.
Figure 1: GetFiles() description
Figure 2: GitFiles() example
