21.7. Document customisations¶
Documentation is important for any software, especially when you make customisations. Documentation can live in many different places, e.g. in a text document on a personal computer or a network drive, in a wiki, in a knowledge base, or directly in the repository where the code sits. Some of these places are more difficult to find than others, in particular for those new to a project.
It is recommended to keep the documentation close to where the code sits so it can be found easily. Some people put it into the README
file whereas others create separate files. Since Mahara comes with a README
file for Mahara, adding project specific documentation to it would always result in conflicts. That’s why there is a CUSTOMISATIONS
file that can hold all of the client specific documentation.
An example file is provided in the codebase. It is set up to use Markdown for formatting its content.
Warning
Do not put any sensitive information such as passwords, keys, or personal information into that file though but store them securely elsewhere. The CUSTOMISATIONS
file is added to the project repository and thus a history of changes is kept. If the codebase were made more widely available, that sensitive information would be exposed.
The file sits outside the htdocs
folder so it is not deployed to a web server and thus accessible through the browser, provided, you only upload the content of the htdocs
folder to your server.