Developer documentation organisation
Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.
Distinction between developer and user documentation
The User docs and the Dev docs were once a combined wiki. They were separated for a number of reasons.
- 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
<nowiki>[[:en:Main page|User docs]]</nowiki>
. 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
:dev:
, for example
<nowiki>[[:dev:Main Page|Dev docs]]</nowiki>
.
Levels of Documentation
The documentation relevant to Moodle development can be conceptualised at three levels forming a loose hierarchy of complexity.
The three levels are the Moodle codebase, Dev docs wiki and Moodle developer courses, which are each described below.
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.
Moodle Developer Courses
This Moodle site has been established to allow developers to learn how to develop and maintain Moodle code.
The content of the site should be instructional and should refer to other forms of documentation (in the Dev docs and the code), rather than repeating it.
The main focus of this site is the Introduction to Moodle Programming course which covers the fundamentals of Moodle development.
More focussed courses could target specific topics such as block development or theme development, replacing Dev docs content that is instructional in nature.
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.
Code
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.
Major categories
- 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.
