This is the third post in a series about Magento development best practices, and it is about readme files. How often have you opened up a module’s directory and all you see is folders? That is the case the majority of the time. The only way you can possibly know what a module does is by finding the original download (where they may have included a pdf or something), or perhaps if you are a developer, your company has a wiki or something for the project where the module was documented. You could also look through the code to figure it out if you are a developer, but that can take time. Chances are, there’s no or little documentation where you need it.
This is really a bummer and it stinks for the Magento community that this is so common. In my opinion, the best place for documentation is to keep it right in the root of the module itself. I think it’s best to make it a txt file or something that can be easily opened in an IDE and easily modified. A pdf looks nice, but is not ideal for continued updates to the documentation if the module is ever updated.
My practice is to create the readme.txt file in the module root right after I create the module directory. I then make sure to continually keep it updated as I progress with the development of the module. That way it’s always up-to-date, and it’s not a pain to take the time to write it all after I’ve written the entire module, as well as you won’t forget about certain points or aspects of it either.
Readme files contain not only information about what the module does and how it functions, it also includes how to use it from every possible perspective (frontend, backend, how to use it’s methods/helpers if needed, etc.)
I encourage all of you to make a regular practice of this. I guarantee it will help you, your team, and anyone else who ever uses your modules.