Open Surface and the value of Public API

Microsoft recently posited the idea of "open surface" as an alternative to "open source". Correctly noting that a stable public API, protocol, standards are of great value.

This is actually a position I have great sympathy with:

• OGC open standards are considerably easier to adopt; then the pay to play ISO ones.
• Sextante - Is propietary software better for developers? noted that when a public API is the only mechanism for communication with developers that the API / Docs / Code examples are very much improved as a result
• This is contrasted with "Open Source Code" translating as open the source and read the code - a different value proposition to be sure!
• API stands for "Application Programming Interface" - and is generally the information needed to use an application or library as a programmer. It documents what can be done on a function by function (or method by method) level. Traditionally this was limited to describing the parameters; inputs and outputs, and for really good docs providing an example use.

Related documentation:

• GeoTools javadocs
• uDig - does not publish javadocs (as they are generated as needed in Eclipse and shown as tooltips during development)
• GeoServer javadocs - I could not find them easily as the website is primarily user focused. As with uDig docs I did not notice they were "missing" as Eclipse generates them on the fly.

I will point that the general approach here is to really lean on tools like Javadocs, or Sphinx that process API documentation that is coded along with the source code.