The only problem I have with it is that the author is terribly fond of weird self-referential puns and wordplay, and I find the docs (and posts and comments) he writes to be basically unreadable.

Even the project names: osh, and ysh, and oils, where osh is short for Oil Shell, but so is OilS I think...

It makes it really annoying and difficult to read, IMHO. Maybe it's just me.