Alexey Zakhlestin's Blog

Programming for Mac and Web

On Documentation


People often debate on reasons of PHP’s success and “not so big success” of it’s more powerful competitors. My belief is, that one of the major parts of PHP’s win was it’s manual. All of the competitors had basic API documentation, but they didn’t have:

  • syntax-highlighted examples for the majority of functions
  • user-contributed comments

It’s actually getting better now (see documentation on Ruby’s CGI module, for example). But no-one is close enough.

One of the main concerns of the language core-team should be documentation. Better the docs are, more people will be comfortable to start using it for solving their problems.

If I have several weeks for digging into sources, I will probably chose the language which I like syntactically. But if the timeframe if small, I would definitely prefer the one which has better docs. Guess which situation tends to happen more often.

Something to think about: