Developer documentation organisation
Distinction between developer and user documentation
- Developer documentation can be confusing for regular users
- User documentation is version specific, whereas developer documentation usually spans versions and can often refer to future implementations
- Separation allows the organisation of the two wikis to be targeted towards their respective audiences
The primary distinction between the two wikis is their target audiences. Documentation relevant to developers should appear in the Dev docs and documentation relevant to general users should appear in the User docs (although most developers will read user documentation and user documentation will often be written by developers).Ideally information should not be repeated in both the User docs and the Dev docs; instead information should be linked between them under the assumption that they will always coexist. To link form the Dev docs to the User docs, create an internal wiki link with the page name proceeded by
:en:, for example
. This will automatically redirect to the current English version of the User docs. Conversely (and probably less likely), when writing User docs pages and wishing to link to the Dev docs, use an internal wiki link and proceed the page name with
[[:en:Main page|User docs]]
:dev:, for example
[[:dev:Main Page|Dev docs]]
Levels of Documentation
The documentation relevant to Moodle development can be conceptualised at three levels forming a loose hierarchy of complexity.
Ideally, to reduce redundancy and increase clarity, there should be little overlap between these levels, so the Dev docs should not include information that is easily identifiable from the code, nor should the dev docs contain instructional material that would be better delivered in the Moodle Developer Courses.
This Moodle site has been established to allow developers to learn how to develop and maintain Moodle code.
The main focus of this site is the Introduction to Moodle Programming course which covers the fundamentals of Moodle development.
The site can also be used for development related projects and activities, such as the Google Summer of Code that involve an element of instruction, or projects that need to make use of the facilities of a Moodle course.
Dev Docs wiki
When describing the Moodle codebase and guidelines for it's use, the Dev docs should be a factual reference rather than an instructional medium (instruction should be achieved through the Moodle developer courses). The Dev docs should also avoid repeating documentation embedded in code, instead showing the organisation of the code at a higher level and exhibiting examples of how the code can be used as a framework. The Dev docs should be liked to the Moodle developers courses site and to a representation of the code where needed.
Another use for the Dev docs is to collect development related informational documents such as release notes, the roadmap, processes used in core development, student projects, tools and meeting notes.
The Dev docs are also useful for documenting projects during development. However, the Dev docs should not be used to host user documentation related to the product of a completed project, this should reside in the User docs instead. Project documentation may remain in the Dev docs indefinitely, however when such project documentation is superseded by later work, it should be mark as obsolete using an appropriate template.
The code itself contains documentation describing classes with their properties and methods as well as general functions. In order to make use of the Moodle codebase as a framework, it is useful to be able to search the codebase for details of classes and functions. This can be achieved by searching an instance of the Moodle codebase using various tools on a local machine.
When needing to describe the code in the Dev docs or the Moodle developers courses, links should be made to an appropriate location in a representation of the code in such a Web based system.
Note: Ideally it would be best to have a single representation of the codebase on the Web so that links to it can be consistent and maintainable. The single system may be one of the two above or another candidate.
There is also the potential to link to pages on http://git.moodle.org to show specific changes made to the code at a point in time, however this does not include the descriptive potential needed when referring to the code.
Organisation within the Dev docs
From a hit-wise analysis of pages in the Dev docs, the most popular pages have been determined. Using this as a basis for a navigation model that allows most users to reach the developer documentation in the least number of clicks, the following main categories of content are to be used. This analysis will need to be performed again in future to see if the model is effective or needs adjustment. See Popular pages for a current view of page popularity.
The following categories will be used to structure the main page of the Dev docs and will be shown in a sidebar on each Dev docs page. Ideally, most popular pages will fall into one of these categories or into a sub-category. It is possible for a page to belong to more than one category.
The target audience should be kept in mind, so the perspective taken in this structure is that of a developer outside Moodle HQ who is potentially finding their way through the Dev docs for the first time.
- Interfaces (core code libraries, APIs, etc.)
- Core development (category needed)
To avoid cluttering the main page with lengthy lists for the sake of completeness, only popular documents will have direct links. Other pages within categories will be accessible through category pages by clicking on the category name or the ellipsis (...) at the bottom of each list.