Anyone who hangs in the Community Server Forums has read someone else say (or has themselves written) that we need more Community Server documentation. I may have complained about aspects of Community Server in the past, but the lack of documentation has never been one of them.
I'm bringing up this subject because I don't know what kind of documentation other developers and Community Server administrators are looking for. I've seen a lot of requests for Application API Documentation because it's easier to read through a document than scan through the code...which is a point I have to chew on a bit.
Let's see, an API doc will list a method, what it does, and how many overloads there are. It would give you a class's base class and that base class's base class. It will describe what the object does and maybe even provide some sample code on how to use it.
I'm not saying that's a bad thing, not at all. But there are certain issues that I think we need to consider before thinking a traditional API is a good idea for Community Server and a wise investment for either the community or for Telligent to undertake.
First, we (as in Community Server enthusiasts) have the SOURCE code. We enjoy the equivalent of the character Ram in Tron
going wild with delight because he was able to drink from a pure energy source. That's what the Community Server SDK is, it's a pure stream. If I see a method in, say the Weblogs class, I can Ctrl-Shift-F and search on “ThatParticularMethodName(“ with a single parenthesis to catch all uses and all overrides. What's the base class of some particular class? It's right there. What are all of the properties in this object? It's right there, either in its class or derived class. Plus we have an incredibly rich debugging environment in Visual Studio 2005 that we can use to reveal a wealth of detailed information about Community Server. That's one reason why I can't agree with investing in classic Application API Documentation for Community Server.
A second consideration is that Community Server is a really young product. I mean, REALLY young. Community Server 1.0 was released in March 2005. I remember it well; because it was released right about the time I was preparing for a dotText Code Camp presentation. Here it is, July 2006, barely 16 months later, and we have a radically different (all would also agree, a radically better) Community Server. It's stunning to look back on all that's been achieved since March 2005. And look at the extent of changes between CS 2.0 and CS 2.1. We also know the entire Theming and Skinning model is going to get an overhaul in CS 2.2, so there's not much likelihood that this accelerated rate of change and progress we've been seeing in Community Server is going to slow down any time soon.
I'm saying a couple of things here about Community Server’s youthfulness and vitality. 1) 16 months may be enough time to create traditional API documentation for a product that doesn't change much, but the current version of the CS 2.0 API has very little in common with it's 1.1 API predecessor of just 10 months ago. I suspect that the CS API of 10 months from now will have very little in common with its 2.1 API counterpart of today. This app changes fast. If we can at the very least record and chronicle the ongoing changes that the rock-n-roll Telligent Developers are making to Community Server, I think we're doing ALLLL-right.
This is a subject that is personally very important to me because, while my role at Telligent may be not clearly defined, I am charged as a "Community Server Evangelist." By definition I am to get information to developers and users about all aspects of Community Server. While I might not personally think that Application API Documentation is a worthwhile investment, I want to be sure I understand the type of documentation users are looking for. Until a better plan comes along, there are other avenues like the new Forums FAQs (not to mention the Forums themselves!), Community Server Docs
, the [DailyNewsShort], and information like the recent White Papers that will evolve to hopefully address each of our individual Community Server needs and interests.
[tags: Community Server]