Dave Burke : Freelance .NET Web Developer specializing in Online Communities

7/25/2006 12:53:37 AM Permalink

While I would agree that the API has changed dramatically between versions, I also understand the desire for developers to have a better understanding of how CS works. One thing we could definitely improve is comments, both xml style and inline. For folks who use the Visual Studio's Object Browser, we are doing a disservice by not accurately reflecting the current state of a class, parameter, or other member. For folks reading/modifying the code, it's also critical that whatever comments exist are accurate, and any "weird" code is explained. Personally, I'd love to see this in the CS v2.x timeframe, though I'm not sure there's time to do a complete once over all the source.


As a side note, I think the API has changed because the focus has been on improving the experience, adding features and fixing bugs. Without time set aside for explicit API design, the interface (from a code perspective) can quickly deteriorate as items are fixed or requirements change. As we begin to focus on our CS v3.0 product and the full web services stack, I think we'll be in a much better place, in regards to API design, out of necessity. When folks download the CS source, they're still thinking of CS as a large product. Once a services layer is available, folks will begin to treat CS as more of an engine with a firm API that they program against. In that scenario, stability and documentation will be need to be a high priority.

Jose Lema |

7/25/2006 2:44:11 AM Permalink

Jose, you half (or 1/3, 1.5, pi/5, pick a number) beat me to what I wanted to say .

The API documentation is indeed pretty bad. Of course those of use who've been involved since the early days of CS don't have as many issues as someone who is just now dl'ing the SDK. Just as a quick exercise the other evening I attempted to look at the source from a 'noob standpoint, and wow, the API for CS is A) huge B) quite complicated (even for seasoned developers such as myself) and C) largely undocumented.

One of the things that makes the .Net framework itself so easy to use is the enormous amount of time MS spent documenting it on MSDN/MSDN2. But, those docs weren't hand written, they were generated from comments themselves that the devs left in their code, ala nDoc style, which I guess gets me to my main point. Why isn't there an nDoc style (or even CHM style) API document available? Easy answer (and Dave, you nailed it in your post): The API wasn't documented inline as it was written. So yes, doing a once over throughout the entire codebase at this point probably isn't feasible.

All developers are guilty of it...who wants to write boring docs/specs/etc in their code, but it's a necessity, especially with a project that has as large of an outward facing presence as CS does (which is only going to get larger with subsequent releases). Going forward I believe there needs to be a rigorous framework in place for checking that devs have doc'd their classes thoroughly. Again, nDoc is a great tool for this (amongst others). Sure it's easy to fire up reflector, or fire up VS and hit ctrl-alt-j, but even better would be something like csdev.communityserver.org where we have a full API outline ala msdn, complete with code examples, related content, expected exceptions that methods can throw, etc. I do realize that hiring someone to go over the code and add comments would be an exercise in futility, but perhaps provide each dev with an hour or so a day with "documentation time" to go back over previous code they've written and, well...document it. And better sooner than later.

As of now (besides just reading through raw source code) my best documentation is Keyvan's Dev Guide series...mainly b/c he provides good examples.

sorry for the rant, but this is a big deal IMO .

jayson knight |

7/25/2006 8:50:48 AM Permalink

With any viable commercial software product, there comes a certain level of expectation on the part of the User/Consumer.  That expectation includes being able to find necessary and accurate information, in an expedient manner, regardless of the subject matter or the medium used.  Until those expectations are met, no matter how great the product, Communuity Server's success in the marketplace will be heavily compromised.  

You started out by saying "I'm bringing up this subject because I don't know what kind of documentation [people] are looking for".  I'd like to suggest that the simple answer is "organized" documentation.  It's not about the topics covered or how the information is conveyed.  

More to the point, the CS Forums address virtually all aspects of Community Server, i.e., configuration, operation, customization, etc.  For better or worse CS Forums have become the first-line resource for information.  Given Community Server's "youthfullness and vitality" (which is NOT a valid defense by the way) the CS Forums may arguably be the most appropriate medium, but with some major shortcomings that beg human attention.

The problem, as I see it, is the significant lack of organization and poor (human)management of the "documentation" that IS available via CS Forums.  For any given subject, there are likely to be dozens or perhaps hundreds of individual threads.  Of these, far too many lead nowhere.  At best, it's like having a printed manual with a 500-page index... but no chapters or any other form of categorization.  

Instead of wondering what new books people might want to read, I would organize the library.

Paul Baker |

7/26/2006 1:21:23 AM Permalink

That's utter rubbish, you have a commercial product that you allow developers to extend, how can they do this easily without API documentation, you're just lazy if you ask me!

D |