Tom wrote:
"The guide is the most valuable resource for prospective BYOND developers"
If you're going to stick with that ridiculous claim, then the guide needs some heavy maintenance.
- Remove the "Meet the Dream Maker" section from Chapter 1. It is a completely worthless wall of text that helps nobody, but surely scares off plenty of people.
- Remove the quotes from the beginning of each chapter. I don't even understand half of them, no less see how they relate to anything.
- The guide is out of date. If you're going to be promoting it as the official learning resource you could at least put some effort into maintaining it. "Choose New Pixmap... from the Graphic menu"?
- The guide needs some color, pictures, and visual appeal. Reading a gigantic wall of black text on a white background is rather tedious (like this post =P). At absolute least, the code snippets should be presented inside of some forum-like DM tags.
- There is a TON of white space. Lets cut down on this so the guide isn't longer than the bible.
- Don't use usr. This is all I ever hear developers whining at each other about, and there's rarely a case to use it. These few cases should be explicitly explained. I'm not sure how often this actually happens in the guide, but just from skimming the Verbs chapter there are several improper uses of it.
- Links to related useful information: From what I've seen, every link in the guide just takes you to another point in the guide. Woopty do? Links would be better pointed towards the reference, or even outside learning materials. Things that are listed in the reference could be linked when mentioned, like on wikipedia.
- Don't be so technical. Most of the guide is dry and confusing because such technical terms are used. There are parts of it that I can barely understand (or just don't agree with), even after mastering the language.
I find the reference a much better learning tool. Hell, that's what half of the guide boils down to anyway.
In my personal opinion, I'd say my incomplete
Tutorial Series gives new developers more motivation, useful knowledge, and understandable hands on experience than the entirety of the guide. You can have a playable project in ~20 minutes, and it holds your hand every step of the way. Plus, it has pictures! On top of that, its posted in a forum. Which means people can directly reply with questions, point out flaws (both of which lead to improvements), and can converse with the community they're getting involved in.
Throwing a bunch of information at people is rarely useful if you don't tell them how to put it all together. I had some serious problems attempting to learn
Lua for GMod, because that's just how their information is presented.
The guide does need an update. But the 'Meet The Dream Maker' section and the quotes give it life. They keep it from being a simple manual and actually make it entertaining to read, in my opinion, though my opinion tends to differ from most. As for the technical terms, use a dictionary. If you are too lazy to look up what a word means, then you shouldn't be programming (or participating in society; again, my opinion).
AZA was working on updating it at one point. It was a pretty decent update, visually, but he lost interest at some point. I'm going to see if I can find the chapters he actually finished.