Name: Anonymous 2013-08-30 22:52
Have the Scheme documentation writers never heard of examples?
I've never seen a community that was so collectively clueless about how to write documentation. And I'm a Slackware user. I don't think anyone has ever complained about the excessive documentation that comes with Slackware.
I might even consider writing some documentation myself, if not for the fact that I can never get anything in Scheme to work, because the documentation sucks so bad. My philosophy is to just move on if I have to work too hard to figure something out. I've come to realize that developers that don't document their work very well are usually not good developers.
Let me elaborate on that point a bit. The software might work as intended, but the underlying code is only part of the project, and by itself has no value. A good design means I don't have to think too much to use it. And when I return to the code in a year, I'll be able to easily figure out what I did and how to extend it.
If I have to work for six hours to figure out how to call a simple function, that's a sign that at some point I'm going to find that my program isn't doing what I thought it was doing. At some point I'm going to say, "WTF? Why was that matrix transposed? It makes no sense." Of course there was no way I could have known that, and there's no way I will ever understand the philosophy driving the development of the library. Then a few seconds later I'll be terrified, "Hold on, if the developer would do something like that, how can I trust the other lines of code that I've been writing for the last two weeks? There's no freaking documentation!" Then I'll move on to a real language, redo everything, and be sure to avoid the mistake of trusting Scheme in the future.
Go to one of the popular Scheme implementations. Just pick one. They're all equally useless. Pick out an extension that does something you need for numerical computing. If there's documentation at all - and there may very well not be - try to use that documentation to write a program. Use all of the important "things" that the extension does. Use those important things in different ways, like you would actually use them in an actual programming exercise where you are actually trying to feed yourself. Can you even figure out how to call all of the functions properly in less than two weeks?
Most of the documentation is just a slopped-together list of functions and a short, content-free description that might (though in most cases probably won't) be sufficient to jog the memory of the developer himself as to what the function should do. There's no chance in hell that a programmer writing a program related to his career is going to spend enough time to figure out how to use the extension. Sure, there are hobbyists who will figure it out, but I'm talking about real work in an environment where money is on the line.
I cannot treat the developers of Scheme as real developers. They're not professionals. Some are, of course, but I'm talking averages here, and the average Scheme developer is of pretty low quality relative to the average Java developer. The average Scheme developer thinks he's much better than the average Java developer because he can use recursion properly and was smart enough to recognize the brilliance of Lisp. Great, but if you measure developer quality in terms of the value of the output in a given amount of programmer time, Scheme developers probably have a negative value, because most of what they do gets in the way of developers interested in making a product that does something of value.
Do I like Java? Not a chance in hell. If I had to choose between Scheme and Java to do something with money on the line, even assuming all the same libraries are available in Scheme and Java, which would I choose? I'd take Java in a second. Scheme could learn a lot from Java about working with beginners.
It's a shame that Scheme has been plagued by crappy documentation. There's no reason that Scheme, on technical merit, cannot be Java. The difference is that Java was written for business applications, and that required documentation, and they got it. The Scheme community has decided that working with beginners is not fun and it has caused Scheme to be viewed as a goofy artifact of the past, rather than the language of the future.
I've never seen a community that was so collectively clueless about how to write documentation. And I'm a Slackware user. I don't think anyone has ever complained about the excessive documentation that comes with Slackware.
I might even consider writing some documentation myself, if not for the fact that I can never get anything in Scheme to work, because the documentation sucks so bad. My philosophy is to just move on if I have to work too hard to figure something out. I've come to realize that developers that don't document their work very well are usually not good developers.
Let me elaborate on that point a bit. The software might work as intended, but the underlying code is only part of the project, and by itself has no value. A good design means I don't have to think too much to use it. And when I return to the code in a year, I'll be able to easily figure out what I did and how to extend it.
If I have to work for six hours to figure out how to call a simple function, that's a sign that at some point I'm going to find that my program isn't doing what I thought it was doing. At some point I'm going to say, "WTF? Why was that matrix transposed? It makes no sense." Of course there was no way I could have known that, and there's no way I will ever understand the philosophy driving the development of the library. Then a few seconds later I'll be terrified, "Hold on, if the developer would do something like that, how can I trust the other lines of code that I've been writing for the last two weeks? There's no freaking documentation!" Then I'll move on to a real language, redo everything, and be sure to avoid the mistake of trusting Scheme in the future.
Go to one of the popular Scheme implementations. Just pick one. They're all equally useless. Pick out an extension that does something you need for numerical computing. If there's documentation at all - and there may very well not be - try to use that documentation to write a program. Use all of the important "things" that the extension does. Use those important things in different ways, like you would actually use them in an actual programming exercise where you are actually trying to feed yourself. Can you even figure out how to call all of the functions properly in less than two weeks?
Most of the documentation is just a slopped-together list of functions and a short, content-free description that might (though in most cases probably won't) be sufficient to jog the memory of the developer himself as to what the function should do. There's no chance in hell that a programmer writing a program related to his career is going to spend enough time to figure out how to use the extension. Sure, there are hobbyists who will figure it out, but I'm talking about real work in an environment where money is on the line.
I cannot treat the developers of Scheme as real developers. They're not professionals. Some are, of course, but I'm talking averages here, and the average Scheme developer is of pretty low quality relative to the average Java developer. The average Scheme developer thinks he's much better than the average Java developer because he can use recursion properly and was smart enough to recognize the brilliance of Lisp. Great, but if you measure developer quality in terms of the value of the output in a given amount of programmer time, Scheme developers probably have a negative value, because most of what they do gets in the way of developers interested in making a product that does something of value.
Do I like Java? Not a chance in hell. If I had to choose between Scheme and Java to do something with money on the line, even assuming all the same libraries are available in Scheme and Java, which would I choose? I'd take Java in a second. Scheme could learn a lot from Java about working with beginners.
It's a shame that Scheme has been plagued by crappy documentation. There's no reason that Scheme, on technical merit, cannot be Java. The difference is that Java was written for business applications, and that required documentation, and they got it. The Scheme community has decided that working with beginners is not fun and it has caused Scheme to be viewed as a goofy artifact of the past, rather than the language of the future.