General developer forum

Hello,

Some of you may have already heard this news as you attended or have watched the Developer Meeting held on Tuesday.

For some time we've been receiving feedback about our developer documentation and we have been trying to find ways to improve upon it (please note we are only looking at the Developer Documentation at this time).

Survey

If you have time, we would really appreciate if you could answer a few questions about your experiences with documentation in general, and the onboarding of new Moodle Developers.

About our project

More recently we have set up an internal working group whose job it has been to look at the current developer documentation (https://docs.moodle.org/dev) and resources, to identify the key issues, and to work out what we can do to improve the situation. We've been working on that internally for the past few months and the key issues that we've identified with the current documentation include things like:

• content is out-of-date, or incomplete
• poor discoverability - pages are not easy to find without knowing key search terms, or how to get to them
• poor searchability - the WikiMedia search is slow and does not give good results
• content is not relevant to specific versions and it is often difficult to identify when a feature became available or was deprecated
• content is inconsistent
• the structure is largely flat
• no clear direction when viewing the landing page
• no quick start, or getting started for new developers
• the WikiMedia markdown is counterintuitive for many who are used to Markdown
• New APIs are not documented quickly and there is no ability to block integration of a feature pending documentation
• Lack of API docs (both PHP and JS)

As part of this process we want to identify the most appropriate solutions to these issues and we have been considering whethe WikiMedia is still the best mechanism for delivering these docs. We have also been looking at contribution workflows.

What we've tried

Most recently we have been trialling some alternative documentation systems, in particular we have trialled the following:

• Sphinx using ReStructedText (RST) both with, and without ReadTheDocs
• Sphinx using Markdown both with, and without ReadTheDocs
• mkdocs
• Docusaurus

We have also tried to consider aspects including:

• Appropriate tooling to ensure that documentation is correctly displayed, linted, spell-checked, and easy to build
• Offline availability
• Migration from WikiMedia
• Introducing Versioning

Likely direction

At this point we feel that it is likely that we will migrate the Developer Documentation to use the Docusuarus documentation generator as we feel that it solves many of the issues we've experienced out-of-the-box, and can be easily updated to address many of the others.

We have been performing some more in-depth testing, smaller-scale migrations, tool development, and structure discovery. We will keep on with this as we try to determine more detail of our migration plan. Once we have a firmer plan in place we will make an announcement and will start to disable write changes to https://docs.moodle.org/dev, which will still remain available to view legacy documentation.

Show me the shiny stuff already

You can see our progress, check out the repository, and build the documentation yourself at https://github.com/moodle/devdocs. You can also view the built documentation at https://moodle.github.io/devdocs.

• View the docs at: https://moodle.github.io/devdocs
• View the repository at: https://github.com/moodle/devdocs

Good content examples

Please note that many of these pages are placeholders, or sample content and are active works in progress. Below are some of the more complete pages which we have migrated:

• Landing page: https://moodle.github.io/devdocs/
• Coding style: https://moodle.github.io/devdocs/general/development/policies/codingstyle
• Activity module plugintype guide: https://moodle.github.io/devdocs/docs/apis/plugintypes/mod
• Access API guide: https://moodle.github.io/devdocs/docs/apis/access
• Testing process: https://moodle.github.io/devdocs/general/development/process/testing
• Peer review process: https://moodle.github.io/devdocs/general/development/process/peer-review

Key features

Some of the key features to highlight include:

• A clear landing page, with an easy Call to Action (Quick start), and prominent category links
  • These are placeholders and we aim to choose more appropriate categories and relevant images once more documentation is in place
• Clear navigation which is always visible, including:
  • Top navbar - this stays the same across all documentation in the site
  • Left navbar - this stays the same for the current category
  • Right navbar - relevant to the current page
• Use of 'admonitions' to highlight tips, information, warnings, notes, and other key information
• Clear code blocks, with a 'Copy to clipboard' button, and syntax highlighting
• Light/Dark mode
• Links to the Moodle Academy for relevant content (currently only used in the Access API)
• Category tags to group content together (e.g. https://moodle.github.io/devdocs/general/tags/quality-assurance)
• Fast and clear search - please note that this will improve further once we have our hosting plans finalised
• Version-specific documenation for Moodle whilst other content is not version-specific (i.e. Process & Policies is not versioned)
• PWA support for mobile browsers, and Chrome desktop, including offline access to docs

Backend features

From a backend perspective we have some additional useful features:

• Linting of all markdown and style - we are currently looking to turn this into a pre-commit hook too
• The ability to have code examples included from separate files (see https://github.com/moodle/devdocs/blob/main/docs/guides/javascript/index.md?plain=1#L428-L430 for example)
• Page reload when content is changed
• The ability to use MDX/JSX to include custom components and templates (see https://github.com/moodle/devdocs/blob/main/docs/apis/access.md?plain=1#L35-L38 for example)
• Links to legacy docs pages can continue to exist in the [\[Page target|Description of the link]] format, and will be automatically updated to point to legacy docs
• Detection of where a migrated doc has been used and warning in console to update them
• GitHub pull requests allow us to ensure high documentation quality, but also for new feature documentation to be written before an issue is integrated
• Much much more

API Docs

We are also looking at the best way to incorporate API Documentation. We can easily generate these with Doxygen and jsoc, but we need to look at how we integrate these with the rest of the documentation.

• https://andrewnicols.github.io/docs/apidocs/master/phpdocs/
• https://andrewnicols.github.io/docs/apidocs/master/jsdoc/

This is an ongoing project and we hope to have some more news, and firmer timescales for you soon.

Best wishes,

Andew Lyons

Moodle Principle LMS Developer