Recently, a user posted a rant about the guide that caught my attention, implying that it was a completely worthless document and doesn't help anyone learn to program.
I never read the guide when I first started. How can it be improved? I'm up for writing a back-to-front tutorial series for DM, and am uniquely qualified for the endeavor, but I need to know what people who have actually read the guide to tell me what's wrong with the existing resources and how things can be done better before I embark on this journey.
ID:2144923
 Sep 7 2016, 4:54 pm
|
|
I think the problem comes down to how dated it is, and focused on a specific type of BYOND game (MUD-like RPGs), because that's what Dan made the engine for. So how can this be addressed? I feel like diverging into different problems encountered in different kinds of games will make the guide too unfocused. | |
I have no idea, I'm good at technical documentation, friendly documentation baffles me. I think the most successful beginner documentation is the tutorial kind that walks you through building a basic game from the ground up. Things like StepBYOND and ZBT, but much more fleshed out and robust.
| |
The current DM guide is a little useless in my opinion I have learned more from these forums than their, what it does is that its more like giving us 2 pieces of paper and telling us to glue it together without actually giving the glue. For example it could talk about switch and input but not how to nest switch into input or what would be better than switch input or certain rules and stuff, I read it front and back and upside down, like Nadrew said the game is pretty focused on RPGs and a new DM guide would be greatly appreciated(one that explores all areas)
| |
The DM Guide is designed for people that have little-to-no experience in programming. For people just needing to learn the syntax and definitions, the blue book has it covered.
I'll admit that I had a lot of trouble learning anything from the DM guide and only after learning JavaScript and C was I able to truly comprehend what's going on in DM. | |
I recently had a look at the C# Language Specification and the Unity Scripting Reference. I've also seen the Java and .NET documentation.
I think what the DM Guide does differently is treating the DM Language and the BYOND Engine (which I'd rather call the DUNG Engine, because I feel that "BYOND" should represent our separation from Dantom's Universal Network Game engine) as the same thing, when they're not. The Engine includes all the built-in types and procs, and the server calls the built-in procs that you aren't supposed to call yourself; whereas the DM Language is just syntax and structure. The DM Reference also includes both language-specific details as well as engine details. It's probably fine since it's so small, anyway. The DM Guide tries to teach the syntax and structure very gradually and comprehensively, which doesn't work too well if people don't read it word-for-word from start to finish. If you're going to teach the syntax, I think what people should know best about DM is its tree structure: indentation levels, block statements. Then there's vars, procs, types, overriding. Treat DM as any other programming language, because its users should too, especially when looking up information. It just happens to have an engine attached. At the same time (while learning the language, or after having learned the language), in a separate guide, you can teach people how to use the Engine, given what they know about the language. Include built-in types and their vars and procs, verbs, skin interfaces and macros and command-line syntax. Of course, the more you know about the language and OOP, the more problems you might notice with how the language and engine are structured... so many global procs... | |
I’ve read the DM guide a few times in the past (and was my first "formal" introduction to programming), and, in my opinion, my biggest concern was the "indigestibility" of information for new programmers. Essentiality, most of the information is given in a long, topic specific list with definitions. While I think this is ok (or even desirable, less searching required.) for experienced programmers, it burns out new programmers trying to learn information that they won’t really need for quite some time, if ever. I felt that led to a lot of missed concepts and applications.
I spent some time (mostly during 2015’s summer season, I haven’t touched it in about two months.) roughing a guidebook that takes an approach of only giving a minimum amount of information about a certain subject that is immediately important or relevant at the time, before moving on to another chapter with the next logical bits of information, to help prevent "information overload", and provide a more logical "flow". [DSGBDM.pdf] [DSGBDM.doc] : Warning: Rough, unedited, overlooked, and filled with possible wrong information. You may review and use any part/design of these documents (I had planned to release it for public/education reproduction, anyhow) if you wish. It’s clearly not complete, and I have some notes of stuff I overlooked that I should have included before chapter 11 (return keyword, verbs, how to run a program), some chapters are basically clip notes, and somethings are simply out of place. I never found "game-specific genre creation tutorials" to help me, so I didn’t put much consideration into including anything like that with this rough draft. I thought that an abundance of code examples, followed by an explanation of what exactly was set up and what would happen was important. A lack of code example explanations were one of the sources of confusion that I remembered from reading the guide. In other textbooks, I have found study questions (answers can be found in the text) and critical thinking questions (answers not directly given) to be helpful and encourage application of the information, but never reached a point where I wrote any questions. | |
You know, I'd be really thrilled to create a new guide. My biggest problems are the concerns of organizing the thing, and of course writing it. Every time I've thought about it, my brain has ended up kicking me.
Many years ago I had the idea of creating "The Green Book", which would have the goal of gathering a lot of stuff like my Dream Tutor series into one book where it would hopefully spur beginner programmers into developing intermediate skills. But it never really went anywhere. I've also thought often that it'd be great to take not just Dream Tutor but similar tutorials, and jam them together into a book organized by the community. Revamping the Blue Book itself might be interesting. I don't think I have the original LaTeX files for it around anywhere, but Tom might. I'd personally like to get it translated into a friendlier medium, like .docx or something similar, and get it into a convenient ebook form. | |
Just putting this out there as a rough concept for a Blue Book II outline:
| |
May i suggest a two guides like one fore beginners that are just coming in and are wanting to learn and it explains a-lot more with a-lot more ways of how to do it and explanation as if you where talking to a kid
and then a guide for more advance users that doesn't need as much explanation etc etc. Because i got the paper copy and other guides and well using all the tutorials on the site where much more easier to under to stand because it was like they where guiding a child and now that i understand it much more i can use the paper back book more and go to the F1 guide and understand it. I suggest this because i'm not a good reader when reading i have to read out loud or have someone read it to me while reading it and there might be others like this who just not understand it without many steps involved but once they get use to everything then they won't need all the steps. | |
I'd recommend for the new guide to help beginner programmers definitions for certain terms. Possibly at the end of the book. Reason being is a lot of new players see the type of stuff experienced programmers write (whether it would be in the developer help or just a BYOND thread) and have no idea what you guys are talking about. It doesn't have to be long, just some idea of what words future programmers should look out for.
| |
http://www.byond.com/forum/?post=2148785
Since most people are interested in RPGs, I'm focusing on a guide on how to do that. Most of our existing guides cover this material, but they do so poorly and teach bad techniques. | |
I think the problem comes down to how dated it is, and focused on a specific type of BYOND game (MUD-like RPGs), because that's what Dan made the engine for.