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.