Documentation?
Is there any documentation out there for the web service other than the .NET sample code? I'm not a .NET programmer, and those projects have enough complexity to them, and MS has enough dependency on their toolset, that the samples are basically just worthless to me. Heck, I don't even use Windows, so even the terminology sometimes throws me for a loop. The app docs have nothing on the web service other than to basically say it exists and the very brief mention of the access code.
By digging around the forum here, I did at least figure out the URL to the WSDL and to the SOAP server. The WSDL helps in the docs department, but really, a WSDL doesn't go very far in that department, plus it isn't exactly reader-friendly. What I'd really like to see is a standalone web page or PDF file that has the following:
An overview of the web service... how to access it, how security is handled, a high-level explanation of how to use it, and a high-level view of what you can accomplish with it.
An explanation of the data types and common parameters used in the API.
A list of all methods, broken down by category. Include with each an explanation of what it does, what the parameters are that it takes, and what it returns.
The current state of affairs exemplifies a problem with Gemini: it's written assuming a very Microsoft-centric world view. The app may be written in .NET, but it's quite likely that the majority of your users are not .NET programmers and many (like me) may not even be Windows users. Yet, everything in the Gemini ecosystem is MS-centric. For example, I'd love to have an SVN hook that didn't rely on a Windows DLL, since my repositories are not hosted on Windows servers (as I bet is the case for many users). Thus, I get to do it myself. And the web service - that should be very platform-agnostic, but example code is only in .NET, which is perhaps the worst choice for non-.NET programmers because the simple example requires so much baggage around it. I guess there's some form of docs provided by VS when you open the project, but that doesn't help me. And though I don't know for sure since I can't make heads from tails of the code, I suspect it only demonstrates the WSE-compliant (?) access method, which, again, means it's just MS developers. At the very least, an example in PHP or Python would probably help a lot of *nix folks.
Anyway, if there are some great docs and non-.NET samples out there that I've missed, ignore all this and point the way. Otherwise, I'd love to see some created.
bobw
· 1 |
|
Wednesday, April 8, 2009, 4:20:15 AM |