Text files, HTML pages or giant comment blocks? What's the end-user's preference?

[PK8]

Hey guys, long time no post. So I'm kind of stuck. I'm trying to work on some new scripts and event scripts, and I was thinking about wanting to explain everything in an HTML file that would be part of a zip but I'm not so sure if that's a good idea for the end-users.

So I want to ask you guys this: Whenever you download a system or a script or whatever RPG Maker resource that requires a zip, would you prefer looking at HTML files that explain everything about the resource? A text file? Or would you rather have it all explained somewhere in the resource's RPG Maker project such as a common event or script code?

[deValdr]

HTML file sounds best. What kind of systems are they if I dare ask? ^_^

[PK8]

Whoa, that was fast! Okay, I just added the poll.

I was thinking, moreorless complex systems which may have require setting up a large number of variables.

[Kain Nobel]

Any instructions and FAQ is better than none, but depending on the system in question there are certain mediums that would be easier to explain with.

Example A.) You have a simple save/load add-on that allows developer specified save slots instead of the usual four. In this case, you'll only have one variable to set, which is the maximum number of save files. Other than increasing the number of files a player can save and load, this script doesn't serve any other purpose

Example B.) Ccoa's Universal Message System, while generally plug-n-play, has a ton of Call Script commands which the developer must learn to use effectively. Certainly, she could've just posted the script and left in comments and that was that, but she took the liberty of making a demo as well just so the developer can see the UMS in action and glimpse at the events.

When it comes to events, either a text or HTML file would go great with these. Event systems themselves, while still plug-n-play, are more sensitive and don't use dynamic variables but rather indexed $game_switches and $game_variables which should all be properly documented. When installing these systems, the developer needs to know how many variables/switches he'll need (and the original ID numbers) so he knows what to name and reserve before importing.

Any documentation is nice, at the very least comments should be applied to everything. For demonstration projects, its nice to have an additional text file in the download. What is especially useful is to packaging your system's demo with the same documentation that is posted on forums, with FAQs and compatibility notes and all, perhaps links to where the system has been posted so people will know immediately where to look for an update.

Its interesting you bring up HTML file (or .chm files even). The scripts that I think would most benefit from one of these detailed files would be a bigger system, such as Guillame's (spelling?) multi-slot equipment system, or pretty much any CBS, ABS or TBS. The only situation where an HTML file would serve more useful than a simple text document would be when the system is complicated, and hotlinks are in place so the developer can easily navigate the info they are reading.