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.
ID:109344
 Feb 9 2011, 9:41 pm (Edited on Feb 10 2011, 12:21 am)
|
|||||||
Not Feasible
| |||||||
If you think your tutorial is useful, then write it up as an article and post it, and we can crosslink it from the developer site.
| |
Hiro the Dragon King wrote:
But the 'Meet The Dream Maker' section and the quotes give it life. I, personally, have quit reading the guide several times because of the 'Meet the Dream Maker' section alone. The quotes could give it life, if they weren't so ridiculously cryptic and unrelated. The short random quotes at the Minecraft title screen are much more acceptable. I don't have to spend 10 minutes reading, and then trying to understand them, before I can jump into the game. Tom wrote: If you think your tutorial is useful, then write it up as an article and post it, and we can crosslink it from the developer site. That's not really the goal of this request... | |
Yes, it's true that the guide was probably not written with today's ADD-riddled 140-chars-or-less Twitter generation in mind. And I agree it could use an update, but, this is something that the community can handle.
The reason I suggested posting your tutorial to the developer section is that you touted it as a useful resource and collecting such things is the purpose of that section. From there it can be easily featured more prominently should it prove useful to newcomers. The guide is but one of many links there. Alternatively, if you or anyone else want to take a shot at rewriting the guide itself, more power to you. | |
I agree that the guide needs an overhaul but I am happy with its current format. I enjoyed reading it when I was starting out (I bought a hard copy of it) because it was more than a reference book.
If it could just be updated with new features and current syntax that would be a great improvement. | |
I agree with Falacy (and if I had he votes I would vote for this as well) I think as well as many others that the guide should be updated. And a lot of the fluff used within should be removed to lessen the length of the book and to really allow people serious in learning to dive into it without having to take the time to weed through all of the useless information and filler. That said, I also think if pictures and diagrams were added it might make the guide easier to read then a wall of text and the occasional post of code here and there. If that code were in DM format that would be wonderful as well.
However, I do like the quotes at the beginning of each section although sometimes I wished that had something to do with what the actual section was about in some way. All in all I think an update would be good for everyone. Although I don't think that the update should come from the community but rather the creators of the tools themselves, as you know more about this than we can possibly know. | |
I like the guide because it has |just| enough off-topic commentary to make it a worthwhile read. Without said commentary, I'd be better off reading the reference from start to finish.
That being said, I think you're confusing the terms 'reference', 'guide', and 'tutorial', Falacy. | |
One thing you CAN do is rename that proc...I completely forget it, but it's around Chapter 6, and it's been updated...Does anyone here remember it?
| |
What proc...?
| |
Ter13 resolved issue (Not Feasible)
A new guide is going to have to be provided by a community effort. | |
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.