Are you a Moodle LMS plugin developer? Whether or not you make your plugins available on Moodle.org, GitHub.com or for internal use within your organization, it is a best practice to include some essential documentation with your plugin in a file called README.md.
What is a README.md file?
A README.md file is a plain text file, like source code, that contains an essential quick start guide for you, other developers, Moodle Administrators and other advanced users, depending on the purpose of the plugin, to help them install and use the plugin. The .md file name extension indicates that this file may contain Markdown formatting.
What is Markdown?
Markdown enables you to add sophisticated formatting, such as headings, lists, emphasize text, links, images, tables and much more in a plain text file using a simple syntax of punctuation and special characters (e.g. , **bold text**, # Top level heading, etc.). This formatting is then converted to HTML when displayed on sites like GitHub, BitBucket, GitLab, Trello and even in some texting apps. Even Moodle supports Markdown. Some code editors and IDEs also include support for Markdown while others may require you to install an add-on extension. Learning Markdown requires a small learning curve (i.e. it's easy) though I recommend that you search for instructions based on the functionality you need rather than trying to memorize all of the possible syntaxes.
Another good reason to use .md files instead of .txt files is that you can easily tell your web server to deny access to .md files from a web browser for security reasons. Blocking access to .txt files can cause parts of Moodle to fail to operate correctly and is therefore not recommended.
What to include in a README.md file
The following is an overview of the basic information that a README.md file could include:
- Basic Overview
- System Requirements and Dependencies
- Installation and Configuration
- Usage
- Updating and Uninstallation
- Known Limitations
- Language Support
- FAQ and Troubleshooting
- License
Basic Overview
This section of the README.md file should include a short description of the plugin, enough to understand its purpose and perhaps some examples of why someone might want to use it.
System Requirements and Dependencies
At a very minimum, you should indicate which version of Moodle is required.
If you have different branches for different versions of Moodle, the README.md file should include a table describing which branch should be used for which version(s) of Moodle.
If you have other special dependencies for this plugin, these should all be listed as well. These could include:
- Dependencies on other plugins
- Compatibility with certain versions of PHP
- Compatibility with certain databases
- Dependency on PHP extensions or installed applications in beyond Moodle LMS’ system requirements.
Installation and Configuration
While the following information may seem obvious to you as the developer of the plugin, it may not be obvious to others. This section of the README.md file should include the following information:
- Where to download the plugin: If you are publishing the plugin on Moodle.org, include a link to the plugin’s page. If it is on GitHub, include a link to the repository. For example, some people might put the stable release on Moodle.org and the development release on GitHub.
- Where to install the plugin file for a manual installation: Don’t assume that everyone knows the directory where the Moodle plugin should be installed, especially when it comes to sub-plugins.
- Installation Instructions: If your plugin has no unusual installation instructions, you could simply include a line like: See https://docs.moodle.org/en/Installing_plugins for details on installing Moodle plugins. If it is a sub-plugin whose type and installation path are not defined in Moodle’s lib/components.json, you will need to indicate that an installation from within Moodle is not possible but that only a manual installation can be completed.
- Git installation instruction: Instructions to install the plugin from your git repository, specifically the git command line that would be used. If you have different branches for different versions of Moodle, it would be helpful to include one line for each of the branches. In the following example, the command will clone the Custom Certificate plugin into the mod/customcert directory and then checkout the MOODLE_401_STABLE or MOODLE_402_STABLE branch:
# For Moodle 4.1
git clone --branch MOODLE_401_STABLE https://github.com/mdjnelson/moodle-mod_customcert.git mod/customcert
# For Moodle 4.2
git clone --branch MOODLE_402_STABLE https://github.com/mdjnelson/moodle-mod_customcert.git mod/customcert
(Note: There are 2 dashes before the word "branch") - Activation instructions: Some plugins such as theme, filters and others, may require you to activate them after they are installed. Be sure to include instructions on how to do this, if it is required.
- Configuration instructions: Depending on your plugin, document the following:
- Plugin-specific settings (if any).
- Each of the plugin’s capability settings (if any).
- Moodle core settings that may affect your plugin.
- Any additional installation steps that may be required to enable the functionality of the plugin, such as adding an enrolment type to a course or adding a block to the dashboard.
- Service account: If your plugin requires access to a service, provide a link to a page where they can get more information about the service, pricing (if applicable), how to sign-up and how to configure the service.
Usage
At the very least, include instructions in the README.md file that will help people use the plugin. This should include any information that might be required to navigate to the plugin’s functionality (e.g., location of a link to a report), and some examples of how one might use the plugin. For example, in my FilterCodes plugin, this section would include a list of all the plain text tags that could be used on a Moodle site and describe the context in which they can be or are meant to be used.
If you have more extensive documentation, you could put it in the Wiki of its git repository, the English Moodle Docs or elsewhere. Just be sure to put it in a place where users of the plugin will be able to access it. For example, it would not be helpful to place your documentation on your Intranet if the plugin is publicly available. Either way, feel free to include links to additional documentation, videos, and other information which could be useful.
Updating and Uninstallation
If a plugin is well designed, there should be no special instructions required for updating it. However, if special instructions are necessary such as to update a sub-plugin, be sure to include these here.
Uninstallation instructions should always be included. Be sure to include how to uninstall it from within Moodle LMS as well as manually.
Don’t forget to mention the path where the plugin is located so that the site administrator will not need to go hunting for that information elsewhere in the documentation. If the plugin generates temporary files, indicate where these are so that they can be removed from the site at the same time.
Known Limitations
Does your plugin have any limitations or known issues? For example, a report plugin may only be able to handle up to 5000 rows in the report. Another example of a limitation might be that the plugin cannot be translated into other languages. Whatever the limitation might be, indicate it in this section to avoid having people report it as an issue.
Language Support
A plugin for Moodle LMS should be developed in English first and have most, if not all, of its strings stored in language pack files to make it easier to translate. It is helpful to provide people with information on how to contribute translations for your plugin using AMOS. If your plugin is not available on Moodle.org/plugins, translations will need to be include with the plugin. Indicate the list of languages that are included and the process for contributing additional translations.
FAQ and Troubleshooting
What challenges do people have installing or using your plugin? Save people the trouble of always asking figuring out solutions to the same questions by including a list of frequently asked questions with their solutions in this section of the README.md file. It won’t stop some from asking the same questions but, when they do, you will be able to point them to your plugin’s FAQ.
License
All plugins which make use of Moodle API (i.e., all Moodle LMS plugins) must be released under the GNU GPL v3 license. This is a condition of Moodle’s license. If you have any questions or are not sure what your rights and obligations are, contact a legal council such as an intellectual property lawyer or a software licensing attorney.
Beyond README.md
Other files you might want to also add to your plugin’s repository include:
- .gitignore – This is a file that tells GIT which files and directories should not be included in your git repository. For example, you might not want to accidentally include temporary files, backup files, SQL files, CSV files, ZIP files, project files and directories created by your code editor, etc.
- LICENSE.md – This file should contain a copy of the GNU GPL v3 software license.
- CONTRIBUTE.md – This file should contain information that tells developers what they need to do in order to contribute to your plugin’s development. For example, you could mention a requirement that all code being submitted must comply with Moodle coding guidelines and pass testing using the Moodle Code-checker plugin.
- CHANGELOG.md – This file would contain a list of the changes for each release of your plugin such as what new features were added, and what was updated and fixed.
- composer.json – This is a file used by many Moodle site administrators to install plugins using composer.
Take the time to create and maintain your README.md file. You may not appreciate it as much today as you will in a couple of years, when someone eventually takes over development down the road or when some kind soul decides that it is worth using and perhaps even contributing to your useful plugin. With very little change, this template of a README.md file could be applied to other open or closed source projects.
Michael Milette
Add a comment: