I was going to make a thread like this.

I have been hopping in and out of BYOND for some years now. I usually loose interest because of frustrations on finding information on the inner workings of BYOND. However, this time around I've had a lot more luck.

The reason why this time around is different is because there's now more than ever a lot of information available in the forums that have been written up by the folks who really understand BYOND. However, I almost gave up because the search for the forums is slow and often times out. But there's a work around that saved me: Google.

I just search BYOND + whatever I'm looking for into Google, and I often find a thread where someone like Lummox JR or forum_account explained how to handle a problem in a proper way with BYOND.

I often wondered how these people got their knowledge on BYOND. Certainly not from the Blue Book. I remember looking up how to set the direction of an object, so I went to Chapter 3: Objects in the tree, and the first section was atomic properties, and in there was dir. Great! It describes that is represents the direction the object is facing. Ok. But what's the value? I was stuck! This was years ago, and then the same thing happened again when I returned to BYOND and needed to remember the values. I recalled immediately that I had done this before when I did it the second time. Not very fun to go through that problem again. I found the global definitions for directions in a thread somewhere, and then realized even later that this information was in the reference.

It should be stated that the Blue Book is good for a once over read to get introduced to BYOND development, then to move on the reference/using the f1 key for pretty much everything. It took me a while to realize that the reference had A LOT more information in it than the guide. Maybe because I figured that the reference was only good for quick look-ups whereas the guide would have better explanation of concepts. That's not the case. It should be stressed more to use the reference, then maybe more people would notice it.

This leads me to believe that the guide should be more focused, or maybe make a volume 2? The reference does a good job of explaining pre-existing procs and vars, but the guide could do a better job of explaining the concepts of BYOND. For instance, I remember reading in a thread where Lummox explained that there can only be one turf per area, despite having different layers. I don't recall reading that anywhere in the guide, and it's kind of important, especially since the layer var implies that you can, well, layer them. Turns out inserting turfs on top of each other in the map editor makes the bottom turf's icon an underlay for the top-most turf. Does that information exist somewhere other than that thread?

I really like BYOND and I want to do a lot with it. I also appreciate the effort that everyone contributes to helping others in the forums. I hope that one day I can return the favor.

BlowStuffUp wrote:

I was going to make a thread like this.

Good points. Though I'm a bit worried about your "Volume 2" idea. Unless I misunderstood you and you meant a "Volume 2" within the existing documentation, I think it'd be best to have all possible information about a subject centralized on one website.


MrStonedOne wrote:

http://byondref.com/

https://github.com/byond-open-reference/byondref.com

Open source, easy to change, changes are reviewed for accuracy, owned by me, and in a familiar format.

This is an interesting idea - make documentation changes require knowledge not only of the subject matter but of Git as well by submitting the changes via merge requests. It would have the benefit of potentially less fluff by going through a knowledgeable person such as yourself along with the added assumption that if the person submitting the changes knows how to use Git, then they also likely know how to use DM. This could equate to high-quality merge requests.

But, it also has its own potential cons. First, the material that goes into the documentation is decided on by one person - you (and anyone you add to the repo with permissions to accept merge requests). If there's any conflict we might end up seeing it split between multiple repositories owned by different people. I think in this case, a wiki would be more approachable and less prone to opinion as it would be more neutral. This is certainly debatable, though, and not always true, but at least the "Discussion" sections within wiki pages could help shed light on issues and solve any subjective conflicts. Second, since the process of changing information requires running Git, editing HTML, making a merge request, and waiting for it to be accepted, I foresee a lot of knowledgeable community members thinking "I can't be arsed to do this, someone else will", and then it never changes. In this case, again, I see a wiki being more approachable with how easy it is to edit the information.


Overall, I still don't know the perfect answer for how to serve up documentation. And I submit that the person with the highest "weight" would be Lummox, since he's already running the show, and Byond would be the one footing the bill if any of us helping out with hosting should get hit by a train. Judging by past experience and what I've seen other engines do with community wikis, I still think just one website - an official wiki - is best, but I can see a strong argument for both - documentation done by Lummox (if he wants), along with an official community wiki done by the community. It would be inconvenient to have two areas to search through documentation, but other engines already do this and the benefits are clear: One website full of unassailable, direct-from-the-horses-mouth documentation, and a separate website (community wiki) that expands on it exponentially.

Beyond that, such as getting people to use it and keep it updated - if it's made technically official by Lummox himself, I think that would be a huge step in the right direction. That includes an initial news post to announce it and continued "marketing" once in a while.

Any more thoughts?