I use the output of my test suite. Between the unit, functional and integration tests this provides a great specification of what my software is suppose to do and what the various internal APIs are. And the great thing about the test suite is that I can prove to a certain degree that the software conforms to the spec because the spec itself is executable and actually exercises the software. Specs that you can't prove are accurate are useless anyways, write a good test suite and use testing tools that output human readable results. Since I work in Ruby predominantly those tools would be mini-test, test-unit, rspec and cucumber.
I'm a Ruby developer in New Orleans, LA and I wouldn't want it any other way here in this city. My skills are in high demand, but that is the state of things here in New Orleans. There is demand for other language developers, mostly PHP, but not nearly the quality of jobs as what is available for a Ruby developer. I suspect that the right answer to this question is highly contingent on the place where one wants to live and work. In San Francisco I know the situation is even more exaggerated than it is in New Orleans with Ruby developers being even more highly in demand.
The answer to this question is always to look around and see what is needed where you are. If you want to move then look at what is in demand where you'd like to move to. In either case, answer the market by adapting your skills. And why choose one language when you could choose multiple. Be a polyglot and pick up Python, Ruby and Erlang. Paired with a knowledge of C/C++ and Java those five languages should keep you in demand in most major markets. PHP developers are a dime a dozen, and the pay reflects that. Only the best PHP developers make good money, and even then I've found it more lucrative to know Perl, than PHP.
But that is just what I know.
Remember, UNIX spelled backwards is XINU. -- Mt.