Where's the documentation?

Status
Not open for further replies.

Fred

Member
Back when SRB2 1.0 came out, lots of brand new things were added, and most people didn't know how they worked. The development team was essentially responsible for publishing the information, even if clumsily. a441 had written a map making guide (for WadAuthor, no less), which was very clear on explaining how the level format worked. SSNTails made a custom character tutorial, with the incomplete example wad, Zim, ending up in a few releases of the game. Even Mystic documented the inner workings of SOCs, SRB2's new scripting language, in the MAINCFG of his mod, Mystic Realm.

But, to me, most importantly of all, there was a gigantic document detailing every single sector, linedef and thing type within the game and, for almost all of them, intricate descriptions of their details, functionality, and particular quirks. It was called the Specials Reference document, and it was "designed to be the ultimate reference for effects used in SRB2." How else were people supposed to know what a Boom Push/Pull thing was? There were still lots of stuff undocumented, like Zoom Tubes, Linedef Executors and NiGHTS mode in general. People had to headbutt the developers and see what would fall out, which is somewhat what Digiku had to do to SSNTails in order to make Botanic Serenity, later even making a full fledged tutorial on the game mode. Thanks, Digi :D

In late 2005, Spazzo coaxed Hotdog003 into making a wadding information repository for SRB2, in form of a Wiki. Like the tasteful chap he is it went through the names TNG2W (The Newbie's Guide to Wadding, or some similar tripe), STARS (which by now I honestly don't have a clue what meant), before steadying at the much more pleasant and descriptive "SRB2 Wiki". People (read: Digiku, DarkWarrior and SonicMaster) began adding stuff to it, essentially porting the existing content carbon-copy into a more streamlined, organized format, while other people wrote tutorials and guides of dubious quality. The wiki also expanded its horizon, and began encompassing all information about SRB2, and not only pertaining to its modification.

Up until 2009, all the releases of SRB2 were essentially bug fixes and polishing of existing content, so all the information was fairly relevant throughout. Some corrections here and there, but mostly everything still applied. That is, until SRB2 2.0 hit the streets. Not only did it reorganize almost every single resource in the game, it changed how a lot of things worked, and added numerous features, such as new sector, linedef and thing types, new SOC actions and even whole new architectures of special effects, such as new linedef executors, zoom tubes (which were never officially documented), rope hangs, slides, reverse gravity, thing scaling, and even polyobjects.

The bad part? None of these features were officially documented. The developers are the only ones who hold the information, and apart from asking them, all people can do is look at how the effects are used in the official maps, or go pry away at the source code. The former is what most people have been doing, which has resulted in poor excuses for tutorials which amount to nothing more than copy-paste jobs and laundry lists of steps to take instead of actually explaining what everything is doing. Some things aren't even detailed, such as the new bosses' behavior, polyobject movement routines like the flags in CEZ2, and the entirety of the laser miniboss in ERZ2.

So, what I ask is: what happened? Why have the developers stopped publishing documentation on the features they create since the Editing section of the website was removed in favor of the SRB2 Wiki? I feel we desperately need a new Specials Reference Document, and we need it badly.
 
The problem is probably that they are too busy actually making the game. Development is progressing a lot faster than it did a few years ago, and I think the devs simply don't have the time to document all those new features, especially considering the sheer amount of them.

That being said, you're right. The editing part of the wiki is in a desolate state. Almost all information is either outdated or incomplete. A Specials Reference Document, or any other kind of documentation would help a lot.
 
I think this is mostly my fault. The existing developers don't even know how some of the things that I added work.

The SVN has an incomplete updated specials html, here it is for what it's worth. Maces, culling plane, and some polyobject actions are covered in detail.

http://ssntails.sepwich.com/specials.html
 
I'll also note that all our documentation didn't come quickly for 0.X and 1.X. When I started working there was no documentation at all, you just had to sit there and guess you were doing things correctly. It took a while for multiple people to step forward and write the proper documentation for everything. Tomorrow, 2.0 will have been out for exactly half a year. That's a lot less time than the 10 years it took for all the documentation for 1.X to be written.

I do agree that our documentation is really subpar, but it's not entirely just a change in work ethic, it's more that it takes a while for everything to get documented properly.
 
The SVN has an incomplete updated specials html, here it is for what it's worth. Maces, culling plane, and some polyobject actions are covered in detail.

http://ssntails.sepwich.com/specials.html
Hey, thanks! That's certainly a step in the right direction. If it's any consolation, it inspired me to work on the Doom Builder configuration.

I'll also note that all our documentation didn't come quickly for 0.X and 1.X. When I started working there was no documentation at all, you just had to sit there and guess you were doing things correctly. It took a while for multiple people to step forward and write the proper documentation for everything. Tomorrow, 2.0 will have been out for exactly half a year. That's a lot less time than the 10 years it took for all the documentation for 1.X to be written.

I do agree that our documentation is really subpar, but it's not entirely just a change in work ethic, it's more that it takes a while for everything to get documented properly.
So what you're saying is, even if I hadn't created this topic, at some point in time you (the development team) would have released thorough documentation of all the game's new features? If this is so, then I must apologize and let you carry on. It just seemed to me that, what with the addition of Wiki, you had no intention of ever doing so.

On a more personal note, I find it odd that you'd write the documentation a fairly long time after the new features were implemented. Writing down everything as I design it just kinda makes more sense to me.
 
Hey, thanks! That's certainly a step in the right direction. If it's any consolation, it inspired me to work on the Doom Builder configuration.

I actually thought this had been released, I guess I was mistaken. Thanks for bringing it up.

So what you're saying is, even if I hadn't created this topic, at some point in time you (the development team) would have released thorough documentation of all the game's new features? If this is so, then I must apologize and let you carry on. It just seemed to me that, what with the addition of Wiki, you had no intention of ever doing so.

I think with the existence of the wiki, we were hoping that the community would step forth and take care of it. That's my own thinking, anyway. We have a few people around here that can read code...

On a more personal note, I find it odd that you'd write the documentation a fairly long time after the new features were implemented. Writing down everything as I design it just kinda makes more sense to me.

Documenting stuff can be annoying. Especially when you're in the middle of working on a map and coding some new feature for it, you really don't want to slow down to write out the explanation of how to use it. You think you'll remember how it all works later on when you get around to finally writing it up, but you don't. :)
 
I think this is mostly my fault. The existing developers don't even know how some of the things that I added work.

Pretty sure that prior to 2.0's release, only one or two devs other than SSN knew how polyobjects worked. As for reverse gravity, speaking for myself, I was having trouble with it because the two main uses of the mechanic, ERZ and TTZ both use totally different effects.

Shadow Hog said:
We are? News to me. I mean, subtle tweaks for 2.0.5, sure, but not much else...

Holidays, school, and other matters from life are usually the culprit here. Now add this to the fact that active development usually requires active developers, each individual developer that isn't around is less wind in your sails to keep you moving.
Also, at least from where I stand, taking the time to beta test, craft textures, and make levels is far easier than taking several hours to write about everything you used. I know for a fact that I'd rather design a few textures, toy with Doombuilder, or play some netgames with experimental features than write about all of this.

Speaking for myself here, but I think that these are problems that are pretty universal as far as the dev team is concerned.
 
I think with the existence of the wiki, we were hoping that the community would step forth and take care of it. That's my own thinking, anyway. We have a few people around here that can read code...
Reverse-engineering someone else's code is always harder than reading your own.

You think you'll remember how it all works later on when you get around to finally writing it up, but you don't. :)
Exactly my point!
 
Status
Not open for further replies.

Who is viewing this thread (Total: 1, Members: 0, Guests: 1)

Back
Top