06-29-2011, 01:21 PM
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.
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.