3
Why Documenting Your Mod Is Important
DavidTheNewKid
When you are first starting to mod you might of looked at how other mods functioned or even delved into code of other mods to get a good example of how to program a mod. You may of watched a tutorial and followed it step by step until you figured out how to continue without the assistance of someone else. In getting more people into this fantastic modding community, documentation is crucial. Documentation helps get more users using mods, more users using mods on servers and more modders modding!
First off I guess we should describe good documentation. Good documentation comes from three separate forms: modder to modder, modder to server owner and modder to player.
Modder To Modder Comments/Documentation
In the modder to modder form you would create comments in your code to help people in the future distinguish what your mod is and how it functions without having to go through the entire code. Whether it be describing what a function takes as an input, returns as an output or how it works any little information helps to make the code more readable. A great tool for modder to modder documentation would be Doxygen for Java where you follow a commenting scheme and the program creates a entire technical documentation for you in the form of a website or a downloadable PDF that you can distribute.
Modder To Server Owner Documentation
Inside of your Planet Minecraft posts you would talk about the installation of your Minecraft mod on servers and how to use certain server side commands. In this you should talk about the full installation of your Minecraft mod starting from scratch as if no mods existed on the server already. You would talk about the prerequisites of your mod (things that need to be done before you can use the mod) whether it be install a modloader or add other mods before your mod can work. you need to tell the server owner this as you can only do so much from assumptions and many times the simplest mistakes in installation can make the mod inoperable. In talking about the prerequisites it may be easier to tell the server owner that they need to do further research into setting up the proper mod environment then linking to a resource that you might've used for the same situation. Then you should talk about the installation steps on what they need to do to install the mod after finishing the prerequisites. It may be helpful inside of the post you can talk about each serverside command step by step or even for each command you can refer them to your modder to modder documentation on what commands does what for the server owner. If you have the opportunity you should try to setup your own server from scratch and install the mod only using your own instruction to make sure it goes smoothly and if you could find someone who hasn't been in the development of the mod try to have them install the mod (this is pretty rare in modding but is very useful in actual programming, we call it user testing).
Modder To User Documentation
This is the most crucial documentation. In your forum post/documentation you need to talk about what your mod does, how it is useful/fun and why the user should use your mod. Also included should be all the steps for installation similar to the steps of installation for the server owner but instead aimed at the user side of operations. Try to use pictures on how to do each step if you can so the user has something to refer to during installation. For a great forum post/ Planet Minecraft post you should have pictures of the mod in action (duh this is required in the posting of the mod). After the installation you would describe how different features of the mod work ingame and if your mod has a lot of lore/items it may be even helpful to create a wikia for the users to refer to but at bare minimum talk about the major portions of your mod and use pictures to fully describe how your mod works. In this stage you are a salesman or saleswoman trying to sell your mod to the general public and the better the mod looks and the easier it is install the more users would gravitate to use your mod. Like I said this is when as a developer need be like an advertiser and sell your mod to the userbase.
I got in a discussion with one of the developers for Forge on why they aren't using a lot of documentation in their code and got the response of that the developer should be able to read the code without documentation. While actually writing the code to be readable in the first place without comments/documentation is noble in the end results it is nearly impossible to do because following someones thought process is often tricky to do. As developers we need to ask ourselves the question of "Why would I program a mod that is inusable by the end user, server owner or even other developer?". I know modding is a hobby for a lot of people and do it for fun but if you want to get further into programming and create amazing projects documentation is key.
Sorry for the long post, I guess I just really, really love documentation!
-- DavidTheNewKid
First off I guess we should describe good documentation. Good documentation comes from three separate forms: modder to modder, modder to server owner and modder to player.
Modder To Modder Comments/Documentation
In the modder to modder form you would create comments in your code to help people in the future distinguish what your mod is and how it functions without having to go through the entire code. Whether it be describing what a function takes as an input, returns as an output or how it works any little information helps to make the code more readable. A great tool for modder to modder documentation would be Doxygen for Java where you follow a commenting scheme and the program creates a entire technical documentation for you in the form of a website or a downloadable PDF that you can distribute.
Modder To Server Owner Documentation
Inside of your Planet Minecraft posts you would talk about the installation of your Minecraft mod on servers and how to use certain server side commands. In this you should talk about the full installation of your Minecraft mod starting from scratch as if no mods existed on the server already. You would talk about the prerequisites of your mod (things that need to be done before you can use the mod) whether it be install a modloader or add other mods before your mod can work. you need to tell the server owner this as you can only do so much from assumptions and many times the simplest mistakes in installation can make the mod inoperable. In talking about the prerequisites it may be easier to tell the server owner that they need to do further research into setting up the proper mod environment then linking to a resource that you might've used for the same situation. Then you should talk about the installation steps on what they need to do to install the mod after finishing the prerequisites. It may be helpful inside of the post you can talk about each serverside command step by step or even for each command you can refer them to your modder to modder documentation on what commands does what for the server owner. If you have the opportunity you should try to setup your own server from scratch and install the mod only using your own instruction to make sure it goes smoothly and if you could find someone who hasn't been in the development of the mod try to have them install the mod (this is pretty rare in modding but is very useful in actual programming, we call it user testing).
Modder To User Documentation
This is the most crucial documentation. In your forum post/documentation you need to talk about what your mod does, how it is useful/fun and why the user should use your mod. Also included should be all the steps for installation similar to the steps of installation for the server owner but instead aimed at the user side of operations. Try to use pictures on how to do each step if you can so the user has something to refer to during installation. For a great forum post/ Planet Minecraft post you should have pictures of the mod in action (duh this is required in the posting of the mod). After the installation you would describe how different features of the mod work ingame and if your mod has a lot of lore/items it may be even helpful to create a wikia for the users to refer to but at bare minimum talk about the major portions of your mod and use pictures to fully describe how your mod works. In this stage you are a salesman or saleswoman trying to sell your mod to the general public and the better the mod looks and the easier it is install the more users would gravitate to use your mod. Like I said this is when as a developer need be like an advertiser and sell your mod to the userbase.
I got in a discussion with one of the developers for Forge on why they aren't using a lot of documentation in their code and got the response of that the developer should be able to read the code without documentation. While actually writing the code to be readable in the first place without comments/documentation is noble in the end results it is nearly impossible to do because following someones thought process is often tricky to do. As developers we need to ask ourselves the question of "Why would I program a mod that is inusable by the end user, server owner or even other developer?". I know modding is a hobby for a lot of people and do it for fun but if you want to get further into programming and create amazing projects documentation is key.
Sorry for the long post, I guess I just really, really love documentation!
-- DavidTheNewKid
