Yet Again, the Problem is the Documentation

There are several unwritten rules about the Internet and we might as well make them clear up front. The first is that everything is great, and if you dont say and acknowledge that its great then you are an asshole and must be ignored and written off as someone who complains.  And I do complain so they are correct.  The second rule is that the documentation sortof sucks, and it does.  It is not intentional on anyone's part that the documentation sucks, or rather is uneven.  It is just the way things turned out.

Now for some details and a specific example and one more time it is not the technology per se that is bad, although of course there are always things one might like to change.  The problem, as always it seems, is that the documentation is either wrong, inadequate or overwhelmed by noise that masquerades as signal.  And that noise manifests itself as "helpful" documentation available on the Internet and authored  by the "group mind" that is, unfortunately, wrong or out of date or replicates what is already there or all of the above and there is no easy way to tell the difference.  As a result, the anarchic state of the documentation makes learning new and possibly better approaches on the Internet annoying and much more time consuming than it needs to be.

Websockets is the “new” approach to client server communication for browser applications. It does not look like much, but it is apparently almost as good as what we had with the Arpanet on day one in 1972.   As I read more about Websockets, I realize that there is a lot of thought that has gone into it in fact just because the Internet is not the ARPAnet and there are a variety of considerations that this forces on the design of technology like Websockets.  

Now Websockets is marked as experimental and is also considered to be incompatible between various implementations/browsers. However, it seems that is old news and that there are good implementations in most browsers and a variety of frameworks to hide differences between browsers.   For my application, I am not too concerned about this as my specific application is more of a proof of concept and we can finesse such things as working transparently on all browsers, for example.

But as always, the documentation is ad hoc.  There are many different frameworks one might use for your server side implementation.  Each of them has a different approach to documentation. Just choosing between the different frameworks (in this case that works with node.js) is itself a chore and a half.

For example, the websockets.org site has the source to an echo client that runs in a browser and is written in Javascript, and they also run a live echo server on their site.   But the source for their echo server is not available.  Why not?  And there is no contact information on their website such that you could ask them that question or any questions at all.

I presume that the people involved in all these technologies and frameworks are not lazy nor stupid.  I suspect that there is a combination of things going on here.  They include such things as (a) being not particularly talented at writing documentation nor enjoying the process, (b) not realizing that such documentation is necessary, (c) balancing the needs of this project with other responsibilities, (d) relying on someone else to do it, and (e) actually believing the groupsource myth that says that other people will write it for you.

My guess, my personal guess, without enough information, is that Websockets is an effort by an elite who simply do not understand or care that people learning their protocol who have not lived with it as they have on their committees will need more documentation and usable examples to make good use of their time.  It works for them.

If you dont like it, well its the Internet, and you dont have a choice.

[Addendum.  As time goes by, I penetrate more of the mysteries and it is not too bad. In fact, it may even be reasonable.  But Jesus, they really don't try to make it easy for you.]