Background

This project initially started off from a discussion between mudrd8mz and emerrill at a table no. 22 during the #mootieuk15 gala dinner on Tuesday 12 May 2015 in Dublin. After some further comments and tweets, it seemed to be quite vital topic and was put as an item for the hackfest happening at that moot on Thursday.

Current problems with the moodle dev docs

• The current dev docs https://docs.moodle.org/dev is just a big mess - we need more structured, reliable and “official” resource for contributors.
• Does not always contain information needed for developers (“Large gap between n00b level and the existing API docs”, lack of tutorials).
• It contains a lot of outdated information.
• It is not clear whether the info is the actual documentation, or a specification. Whether it was ever implemented or just left unattended by someone (e.g. the most valid and up-to-date dev docs on a topic can be sometimes found as a page in the User: wiki namespace, labelled as “draft specification”).
• A lot of information has never been reviewed / confirmed. Misleading information could have been put by anyone (for what they thought was a good reason) - does not help reliability and actual usefulness of the docs.
• When a code / API is created / updated, there is no guarantee that the dev docs will be written / updated (although we have processes in the tracker for things that require dev docs change).
• It needs a lot of self-discipline to maintain branch-related info (when the API was introduced, what was changed in each release etc).
• Mediawiki has its limitations (tracking individual line’s changes, for example).
• Offline version not available.
• No credit given for updating the dev docs at https://moodle.org/dev/
• Not clear identification of what version the new/old APIs belong to
• Fred: Not moodle.org, but who reads upgrade.txt anyway? David: ?

Proposed solution - summary

• Keep the dev docs (not user docs) in moodle.git together with the code itself.
• Formatted as Github flavoured Markdown - makes it look good at the web
• Eventually have a viewer/browser in-built into Moodle itself, if needed.
• Patches are integrated only if they are coming together with the matching relevant docs update.
• Dev docs changes go through the same peer-review processes as normal code change - making them more reliable and trustworthy.

Proposal details - to be discussed

Directory structure

David: I was originally thinking about distributing them across the codebase, similarly to what we do with upgrade.txt files. But as we will need a new folder (with multiple files and eventually subfolders), having a dev docs for, let us say, all activity modules would be problematic (/mod/docs breaks BC, /mod/.docs sucks is far from optimal etc). So currently, my +1 is for a common single root (like Linux kernel does it), e.g. /docs or /dev or /devdocs or /Documentation or so) with the content structured within it. Alternatively, what about mix of both. So the core APIs would be in the root /docs but if it is a plugin-specific docs, it would be like /mod/workshop/docs/

Andrew Nicols: I was also thinking about this and agree, this should be in a single folder and replicate some of our directory structure within that as required. We should also put developer documentation within a subfolder (e.g. docs/dev) because we may also want to move our user documentation inside the same kind of structure. Of all of the tools I looked at, I didn’t really find any which would handle distributed docs well (YUIDoc/Selleck does handle this, but not well). Let’s keep it simple and do ourselves a massive favour!

Damyon: I strongly disagree that the docs should be in the same repo as the code/production install. Having a separate repo with matching branch names gives you all the same features as sharing a repo, but makes it easier to split the code from the docs. E.g. I want to host the docs but I don’t want to clone the entire 200MB+repo. I want to draw entitiy relationship diagrams, but I don’t want to add large images to the code repo. I don’t want to be exposed to XSS attacks from the docs. (Note: repo size IS an issue when you are hosting 100s of moodle sites).

What else do we want to with it

Andrew Nicols:
How about we move all of our upgrade.txt stuff here and format them as markdown. We could move them wholesale, or have a CLI script to find them. We should also have a CLI script to generate a complete changelog (broken down by component) from all of the combined upgrade.txt files found within Moodle

Add a CLI script to generate a complete changelog for each release version (to be run by integrators as part of the release process). We can do this using git log. We may also want to integrate with the Moodle tracker to fetch further information.

Files naming rules

Case (all lower case?), spaces?

Build tools

Andrew Nicols: I propose that we don’t do this ourselves. There are tools out there which are designed for this purpose from people who do this as their bread-and-butter. Sure, we can have it hosted using GitHub’s standard MarkDown formatter, or we could look at something which is designed for this kind of thing. The ones which spring to mind are asciidoc and readthedocs.org. I favour RTD and you can see examples of it all over the place.

Readthedocs.org is probably one of the best examples and their solution means that we get a whole host of features, including:

• search tools
• built-in translation support
• local build tools
• local test tools (server hosting pages upon request during authorship to speed things up)
  theming support
• optional (and free) hosting of the docs. We can have them automatically pull from git.in.moodle.com or github.com and checkout each of the branches and build our docs, serving them on somewhere like https://moodle.readthedocs.com - they also support custom subdomain hosting so we could keep them at https://developer.moodle.org

What doesn’t fit in the new solution

Andrew Nicols: Unfortunately, not everything will fit into this brave new world. The obvious thing which would not be catered for is feature specifications. We need to look at where we handle these, how we publish them and how we publicise them.

Martin: Surely there’s quite a lot of docs.moodle.org that should not be in git (ie anything not verson-specific). I think it’s best, to start with, to just consider the API docs (https://docs.moodle.org/dev/Core_APIs) and do that WELL before doing anything else.

Examples of the approach

• https://github.com/maths/moodle-qtype_stack/blob/master/doc/en/index.md

Issues

• TeX filter (Andrew N: “How is this an issue.. Do we need tex in developer docs now?”)
• Interaction of these with phpdocs in functions. Will there be too much duplication?
• Consistency of dev docs … shouldn’t we be importing/converting gitified docs into the docs wiki as well?

What is missing from this proposal

Damyon & Martin: A summary of a good percentage of the existing docs pages including some “categorization” of each page, whether it is a good or bad example, whether it is up to date and whether it should or should not exist in the new docs system. Some broad categories from the dev docs overview: Core API page, Plugin API page, Project Specification, Concepts and Guidelines, General Developer Info, Overview