After migrating a number of key documents we found that some documents needed to be versioned, but many do not. Several key documents were migrated to Sphinx, using both ReStructured Text, and Markdown but it was ultimately discarded as the versioning support for Sphinx is restrictive. Sphinx both natively, and using ReadTheDocsĪ number of other tools were also assessed and discarded as they were seen to be immediately unsuitable.Discarded as being too immature, in particular due to the number of very immature plugins with no support.Discarded as it is heavily tied to MDN at this time.MDN's Yari tool, used to create the MDN Documentation.clear landing page to allow relevant information to be found quicklyĭifferent options were assessed, including the option to introduce new features and changes to the existing Wikimedia-based documentation, and migrating to a new documentation system.Īs part of the process the working group assessed several other solutions, including:.the ability to link issues to Moodle tracker issues and hold new features from being integrated until appropriate documentation exists for them.the ability to easily remove legacy content.the ability to link content to specific versions of Moodle.the ease of editing when most developers are used to GitHub Formatted Markdown (GFM)Īs part of an internal process, several sessions were held to identify the key features required to improve the Moodle developer documentation, these included:.searchability - the quality of the search tools.discoverability - finding relevant information using the interface and.the ease with which information can be found, including both:.large quantities of stale or irrelevant information, including:.Documentation can be updated after logging in with standard credentials for .Īnecdotal feedback from a range of sources, including in-person discussions, forum posts, and online discussions suggests that there are a number of limitations with the current approach, including: The current developer documentation has over 2,000 pages, and is written and updated using the MediaWiki platform. The Moodle Developer documentation has been a key resource for all Moodle developers for over fifteen years.
0 kommentar(er)
