I've felt this way for quite a long time but only now decided I'd approach the subject. This isn't a personal attack at whomever is responsible for the documentation, but an attempt at a constructive critique of why it's bad and how it can possibly be made better.
The first and perhaps most glaring issue is this damned thing: http://www.byond.com/members/?command=reference&path=proc. Most of the time when I search for a topic about Byond development I get these pages near the top of my search results that are completely broken and devoid of any information. Please take them down.
The second issue is that my other search results might be a page like this: http://www.byond.com/docs/guide/chap12.html, which is missing the left sidebar frame that has all other categorized topics that this one has: http://www.byond.com/docs/ref/. Please no more frames.
The third issue, and this is admittedly more subjective because I'm not 100% sure on it (just an educated guess based on the above two issues existing), that the Byond documentation is hardly updated because it's only accessible to Byond employees to edit.
The fourth issue which is more objective is the fact that the reference pages are severely lacking in information and examples:
"4. file2text
The file2text instruction reads a file into a text string. This could be used for a variety of purposes, including access to output generated by a shell() command."
...No examples. No other information. And there are dozens of these, perhaps hundreds. Some documentation does have examples and is fairly well-written, though, so it's not a problem everywhere. But it is still very common.
The fifth issue is that there several places to find documentation. The DM Guide ( http://www.byond.com/docs/guide/ ) and the DM Reference ( http://www.byond.com/docs/ref/ ), so if you want information you need to check for it in two different locations.
So in summary, for the last, I don't know - 7 years? Maybe more? Maybe this has been a thing since Byond was a thing? You've had people wading through molasses to try and get to the information they need in order to use your engine.
How can we fix it?
I don't know what has to be done, but I know what _can_ be done. If the Byond team makes a huge deal (announcements, a new homepage link, etc) out of hosting a wiki that needs help from everyone for accuracy and to keep updated, and have it literally replace ALL existing documentation (and I mean ALL of it), I bet that would solve a lot of problems.
Making it the only place to get documentation means that EVERYONE is visiting it, which means it will have hundreds or thousands of visits every month looking over the information, many of whom will want to improve on it or fix it. Sure, you'll probably get a few people fighting over edits or vandalizing a few pages, but those are easy issues to fix with minor administration and utilizing the wiki's history. Click one button and all edits a person has done are rolled back. Another few clicks and they're IP-blocked. Done. Or get an extension that does all of the above faster and better. Spam is not a problem if you're using Mediawiki and you have the right extensions enabled. I've been managing Mediawiki wikis for years and I've learned that all of my problems had simple solutions (shameless plug: http://www.colonial-marines.com/wiki - no spam at all)
You could even have a "how to" guides page for how to make save files or ban lists or admin commands or how to use the latest technologies, like setting up CI runners in Gitlab for your project, using Atom as an IDE for both coding and compiling (something I do myself and would be happy to write a guide for), or using Python and sending Byond server messages to IRC or Slack.
This wiki could be an immensely powerful weapon, not only for the above but also against bug reports or common questions here on the forum, too. And obviously, it would be the beginning of the end for the current problems with Byond documentation.
I truly believe that if you guys grab this by the balls and go all-out, it can be one of the biggest improvements to Byond that have ever been done. You could easily increase Byond's popularity simply by making the information easier to get to, so you might even indirectly increase membership as a result. Easy-to-access documentation = Super easy to learn = more people get into it = more potential members.
Anyway. That's my 2 cents. Let me know what you think.
EDIT: Added "fifth issue", I forgot about the two different places to find documentation.
^Also what do you need help on? Since this is *DEVELOPER HELP* not *complain why BYOND is bad and say BYOND should do A, B, and C without offering a possible way that A, B, and C could be done*!^ | |
There was a byond wiki for quite a while, though it's been gone 10 years now.
https://web.archive.org/web/20071023063145/http:// bwicki.byond.com:80/ | |
Rahlzel wrote:
I've felt this way for quite a long time but only now decided I'd approach the subject. This isn't a personal attack at whomever is responsible for the documentation, but an attempt at a constructive critique of why it's bad and how it can possibly be made better. This reference has been broken for years. It's dumb that it still appears in Google results. Easily fixed by either removing it, or having Lummox add it to robots.txt The second issue is that my other search results might be a page like this: http://www.byond.com/docs/guide/chap12.html, which is missing the left sidebar frame that has all other categorized topics that this one has: http://www.byond.com/docs/ref/. Please no more frames. Well, one of those is the guide, one of those is the ref. Just remove the chap12.html; bam you're at the guide. The third issue, and this is admittedly more subjective because I'm not 100% sure on it (just an educated guess based on the above two issues existing), that the Byond documentation is hardly updated because it's only accessible to Byond employees to edit. The documentation is updated everytime a new feature or bug fix is added. Make a compelling case for a certain piece of documentation to be added, and it'll be considered by Lummox. The fourth issue which is more objective is the fact that the reference pages are severely lacking in information and examples: The reference page for file2text has all the info you need. How can we fix it? The issue with a wiki is: there is only one BYOND staff person. Do you really want volunteers curating BYOND's official knowledge base????!?!?! I mean, I would do it, and have wanted to set up a DokuWiki for BYOND before. Importing the current reference is easy enough. | |
The reference page for file2text has all the info you need. Yup, I spaced out and forgot about the second place to find documentation, which reinforces my interest in combining everything into one place to get the documentation so that mistakes like mine don't happen. The issue with a wiki is: there is only one BYOND staff person. Do you really want volunteers curating BYOND's official knowledge base????!?!?! I mean, I would do it, and have wanted to set up a DokuWiki for BYOND before. Importing the current reference is easy enough. I honestly didn't know it was only one person. I assumed it was a group. But my answer is still 'yes', a volunteer official knowledge base can still be far better than what we have now. | |
The first and perhaps most glaring issue is this damned thing: http://www.byond.com/members/?command=reference&path=proc. Most of the time when I search for a topic about Byond development I get these pages near the top of my search results that are completely broken and devoid of any information. Please take them down. This is the biggest issue for me. As far as missing information goes, I get a lot of my more complex solutions from Ter, Kaiocho, and Nadrew's many detailed solutions to developer help questions that have been archived over the years. It may not be an ideal situation, but the information is out there for those who search for it. I'll also wager that the new discord channel's #serious-dev-help channel has been a great resource too. What would be nice is to grab a bunch of their posts and include them in some organized fashion in the http://www.byond.com/docs/ref/ page. | |
I mostly learned DM from the offline reference.
Have you ever pressed F1 in Dream Maker? One of the strangest things about this community is that I regularly run into people that don't even know that you can open the offline reference in Dream Maker and look up built in procs and variables. A lot of us have tried to fix things, information-wise. We've generated a huge amount of resources and taught a lot of people stuff. On the one hand, I get yelled at for how I do it, and told I shouldn't do it, or I don't know what I'm talking about. On the other, we get told we're not doing enough. If you guys want a full top-to-bottom reference overhaul, you guys are gonna need to give me an incentive. I've volunteered a huge amount of my time already. I still continue to do so. If you guys want to pull a fundraiser to have a new guide written, I'm open. But it's gonna take me at the very least 300 hours of my time. If you want to pony up $4,500 to pay for my time to do it, I'm all game. But as it stands, you guys have gotten thousands of hours of my time as a volunteer already, and I've gotten a lot of shit for it. Yeah, it's all nice to say: "We should have volunteers fix this." That's a great idea. It's a huge project. You can't just ask anyone to do it. Resources written by the incompetent are worse than no resources at all. Plus, even some of my own resources aren't very good despite the fact that I've volunteered my time and know what I'm doing. Sometimes you are just wrong, or things don't work out as you'd have liked. | |
Might as well slide Ter a packet of Doritos and a litre of Mountain Dew, because he'll do it for us. Right?
Have you ever visited developer resources? It's one of the most helpful areas on the site. In fact, it's one of the most helpful resource documentations I've ever come across for any language. Hundreds of already done and commented tutorials? Plus you can see the end result? I'm game. Another documentation is here. This has been around for a longtime, use google. http://www.angelfire.com/games4/byond/ Open up dream maker and press F1. It's also extremely useful. Incredibly, in fact everything has an example. Most programmers keep this open when they write code. And yes, it is categorised. The BYOND guide is decent but a bit obfuscated. I read it to a point. BYOND Discord channel. If you have any questions you're immediately helped out. Youtube tutorials by MrCutlery4 (I believe he's still on there). There's a lot of good stuff here. My only gripe is that Lummox shouls replace the website reference with the F1 reference. | |
Ter13 wrote:
Have you ever pressed F1 in Dream Maker? I've been dabbling with DM for a few years now and I never knew about this. If you're saying that this is common, then I'd respectfully suggest that it's an issue not with the user but with the documentation or program itself... http://i.imgur.com/9LqhOl3.jpg. A lot of us have tried to fix things, information-wise. We've generated a huge amount of resources and taught a lot of people stuff. On the one hand, I get yelled at for how I do it, and told I shouldn't do it, or I don't know what I'm talking about. On the other, we get told we're not doing enough. I hope you understand that I wrote this topic with the intent to improve Byond documentation and not to attack its (extremely helpful) users such as yourself who have been fighting the good fight on the forums. In fact, I believe improved documentation and access to it would lessen the need for this community's helpers to get involved when either A) the user that needs help can access an entire page based on a single proc that covers examples and troubleshooting, which is adequate enough to answer their question, or B) you and other helpers know where this page is and can simply link to it. The best part is, if the page you link to doesn't actually have the information the user needs, then that helper can make a note and edit it. Done. Now all future questions benefit. If you guys want a full top-to-bottom reference overhaul, you guys are gonna need to give me an incentive. I've volunteered a huge amount of my time already. I still continue to do so. Yeah, it's all nice to say: "We should have volunteers fix this." That's a great idea. It's a huge project. You can't just ask anyone to do it. Resources written by the incompetent are worse than no resources at all. Plus, even some of my own resources aren't very good despite the fact that I've volunteered my time and know what I'm doing. Sometimes you are just wrong, or things don't work out as you'd have liked. The goal was to have everyone pitch in. Your help would certainly be appreciated, but it doesn't need to be all done by you. It would be a relatively simple matter to copy/paste what we have now into a wiki and get it organized. The brunt of the work, in my mind, would be what comes after - we'd all be helping each other by adding to it as-needed: examples, error resolution, and other important notes for every subject or proc. | |
Just to preface my response, I don't take your comments as an attack in any way, so in the same vein I hope it comes across that nothing I say here is out of defensiveness.
The DM Guide is quite old. It would indeed benefit from an overhaul, but like Ter said, that's not a simple project. Nor is it the kind of thing that everyone can simply pitch in on. Writing a new guide or even updating the existing one requires a strong, coherent voice, and that means one writer. A wiki sounds good in theory, but it would need to be managed well to 1) deal with inevitable defacement issues and 2) the influx of people who think they know what they're doing but don't. Also there's the question of what actually belongs in the DM Guide, or the Blue Book as it's called. Some stuff, like explanation of various error messages, doesn't go there; we have the Red Book for that. And for a long time now I've pondered writing a Green Book to explain the intermediate stuff, which isn't suited to the Guide. Regarding the Dream Maker UI, I can think of oh so many ways that it's terrible (mostly because I've been told all about them), but the help setup is, IMO, not one of them. I mean Help is a menu item and if you hover over it, you see a dropdown of options where the reference jumps right out. | |
Those are perfectly valid points.
It's a risk assessment. Does the risk of replacing all documentation with a community wiki outweigh the benefits of what we have now? I would answer 'yes', but I'm unqualified. I'm able to make the wiki and get it started, but I don't know the community and code well enough to make "the" decision. EDIT: Although I agree that one or two people should oversee its accuracy, I strongly disagree that it needs one writer. The overseers would only need to verify code or settle an impasse. | |
Don't take what I wrote as an attack or overly defensive either.
Rahlzel wrote: I've been dabbling with DM for a few years now and I never knew about this. If you're saying that this is common, then I'd respectfully suggest that it's an issue not with the user but with the documentation or program itself. If you didn't know that there's a help menu in Dream Maker that contains the resources, unfortunately you have never actually read DM's documentation at all. Basically, we could accuse you of not having attempted to learn to use Dream Maker in a way. That's... Not good. It's really not good. Blaming the program for this is even worse. Nearly every single standard program on a computer system comes with a help menu, and if you don't know something about the program, the shortcut for opening it is almost always F1. I don't say this to be rude or make you look stupid. But realistically, if you want to program, basic computer operation is something you should have well out of the way off the mark. | |
I don't use Dream Maker. I've been writing code and compiling using Atom in order to avoid Dream Maker, and I Google needed documentation. That's why I wasn't aware of the F1 menu.
| |
Rahlzel wrote:
I don't use Dream Maker. I've been writing code and compiling using Atom in order to avoid Dream Maker, and I Google needed documentation. That's why I wasn't aware of the F1 menu. Okay, that makes sense. I apologize for assuming you were using Dream Maker then. | |
Writing A New One wrote:
Yeah, we covered that in the three posts above yours, but thanks. Lummox, your descriptions of blue book, red book, and green book could easily go into the wiki. I don't see any reason to separate that stuff. When there's one location to find what you need, that by itself is a tremendous aid when searching for needed information, not Googling around everywhere. Out of curiosity I Googled documentation for other engines. Every one of the popular engines has a community wiki: Unreal Engine 4: https://wiki.unrealengine.com Unity: http://wiki.unity3d.com/index.php Source: https://developer.valvesoftware.com/wiki CryEngine: http://docs.cryengine.com/display/CEMANUAL/ CRYENGINE+V+Manual HeroEngine: http://hewiki.heroengine.com/wiki OpenGL: https://www.khronos.org/opengl Ogre3D: http://www.ogre3d.org/tikiwiki Someone's probably thinking, 'well yeah - those are massive projects with thousands of people - of course they can do a wiki'. And you're right. With a lot of coworkers it's probably child's play to keep wikis updated and vandalism-free. And I would argue that these projects and communities are popular and large as a RESULT of having awesome documentation. The easier it is for people to get into a project, the more people will do it. If Unity's documentation was not only meager but also split between several websites, and Google results kept popping up that led to a dead page, but I'd steer clear of it. As usual, no offense intended. Now that I'm here and I'm somewhat familiar with Byond I don't plan on leaving because of the documentation. As a newcomer I'd get scared away but as a "resident" I can tolerate it. An alternative option is that you could offer access to editing the current documentation to a group of trusted people (not me - people like Ter13 or Super Saiyan X or whoever) in order to beef it up. That has its own set of pros and cons as well, but maybe it's more appealing. | |
Could just have dm open with the reference for when you need to look at something.
also http://www.byond.com/docs/ref/ | |
Is there any reason why somebody couldn't make their own wiki with useful documentation? If it's good enough the BYOND staff could always decide to make it the official documentation if it's good enough, assuming they wanted that.
That way we'd have proper documentation without having to take up time of the staff. | |
HiddenKnowledge wrote:
Is there any reason why somebody couldn't make their own wiki with useful documentation? If it's good enough the BYOND staff could always decide to make it the official documentation if it's good enough, assuming they wanted that. we could that's why i purchased a domain and webspace http://wiki.byond.games/ rip | |
^