Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Plugin documentation: Difference between revisions

From MoodleDocs
(discussion link)
(→‎Where should the documentation go?: removing requirement of editing an existing docs page)
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<p class="note">'''Note:''' This article is a work in progress. Please use the [[{{TALKPAGENAME}}|page comments]] or the [http://moodle.org/mod/forum/discuss.php?d=212264 Plugin documentation] forum discussion for any recommendations/suggestions for improvement.</p>
Plugin developers, maintainers and users are welcome to include documentation about their plugin in the [https://docs.moodle.org English Moodle Docs]. Of course it is fine to have documentation elsewhere, such as the Github wiki, however one advantage of including documentation in the English Moodle Docs is that 'Moodle Docs for this page' links in Moodle (when logged in as a teacher or admin) can lead directly to your plugin documentation (as explained in [[:en:Header and footer]]). And, very important, it will then be very easy for translators of Moodle Docs to add translations for this information.
 
 
Plugin developers, maintainers and users are welcome to include documentation about their plugin in the [https://docs.moodle.org English Moodle Docs]. Of course it is fine to have documentation elsewhere, such as the Github wiki, however one advantage of including documentation in the English Moodle Docs is that 'Moodle Docs for this page' links in Moodle (when logged in as a teacher or admin) can lead directly to your plugin documentation (as explained in [[:en:Header and footer]]).




Line 10: Line 7:


* EITHER typing in the browser address bar: <code><nowiki>https://docs.moodle.org/en/Plugin_name</nowiki></code> (where ''Plugin name'' is the name of the plugin in the plugins directory)
* EITHER typing in the browser address bar: <code><nowiki>https://docs.moodle.org/en/Plugin_name</nowiki></code> (where ''Plugin name'' is the name of the plugin in the plugins directory)
* OR browsing to a page in Moodle for the plugin and then following the 'Moodle Docs for this page' link.
* OR, for an activity or other plugin which has one or more pages in Moodle, browsing to the page in Moodle for the plugin and then following the 'Moodle Docs for this page' link. This will result in a link of the form docs.moodle.org/en/mod/pluginname. The page can then be redirected to docs.moodle.org/en/Plugin_name by adding the text <code><nowiki>#redirect [[Plugin_name]]</nowiki></code>.
 
If you decide later that you want to change the name of the page or create redirects to the page, please email Helen ([mailto:helen@moodle.org helen@moodle.org]).


==What should the documentation include?==
==What should the documentation include?==
Line 22: Line 17:
|type = Enter the plugin type e.g. activity, block, filter
|type = Enter the plugin type e.g. activity, block, filter
|entry = Enter the plugins directory link
|entry = Enter the plugins directory link
|tracker = Enter the bug tracker URL
|discussion = Enter the link to the forum or discussion thread
|discussion = Enter the link to the forum or discussion thread
|maintainer = [[User:Maintainer name|Maintainer name]]
|maintainer = [[User:Maintainer name|Maintainer name]]
|float = Enter left or right to make the box float to that side (optional)
}}
}}
</pre>
</pre>


Note: If there is not yet a discussion thread about your plugin, please create one in the [http://moodle.org/mod/forum/view.php?id=44 Contributed plugins forum].
Note: If there is not yet a discussion thread about your plugin, please create one in the [http://moodle.org/mod/forum/view.php?id=44 General plugins forum].
 
Note: Please make sure that the page linked in 'User:Maintainer name|Maintainer name' actually has your relevant details (profile), or a link to an existing profile in Moodle or elsewhere.


The documentation may also include
The documentation may also include


* A features overview with screenshots
* A features overview with screenshots or videos.
* Installation instructions
* Installation instructions


Plugin documentation examples: [[:en:Stamp collection module]], [[:en:Profile switches]]
Plugin documentation examples: [[:en:Stamp collection module]], [[:en:Profile switches]].


==Which version of the user docs should the documentation be added to?==
==Which version of the user docs should the documentation be added to?==


Plugin documentation should be added to the most recent version wiki in which the plugin works, for example if the plugin works in Moodle 2.3, it should be added to the [https://docs.moodle.org/23/en/ Moodle 2.3 docs wiki].
Plugin documentation should be added to the most recent version wiki in which the plugin works, for example if the plugin works in Moodle 3.4, it should be added to the [https://docs.moodle.org/34/en/ Moodle 3.4 docs wiki].
 
Please note that, as part of the 2011 docs wiki clean-up, documentation pages for older plugins (in the old modules and plugins database) were deleted from the newer version wikis. However, the documentation is still available in the [https://docs.moodle.org/19/en/ Moodle 1.9 docs wiki]. When a plugin developer updates their code, if the original documentation page was deleted it can be recreated in a newer version wikis.  


==I need help!==
==I need help!==
Line 52: Line 49:


[[Category:Plugins]]
[[Category:Plugins]]
[[Category:Plugin documentation]]

Revision as of 13:13, 23 August 2018

Plugin developers, maintainers and users are welcome to include documentation about their plugin in the English Moodle Docs. Of course it is fine to have documentation elsewhere, such as the Github wiki, however one advantage of including documentation in the English Moodle Docs is that 'Moodle Docs for this page' links in Moodle (when logged in as a teacher or admin) can lead directly to your plugin documentation (as explained in en:Header and footer). And, very important, it will then be very easy for translators of Moodle Docs to add translations for this information.


Where should the documentation go?

A new page may be created in the docs wiki by

  • EITHER typing in the browser address bar: https://docs.moodle.org/en/Plugin_name (where Plugin name is the name of the plugin in the plugins directory)
  • OR, for an activity or other plugin which has one or more pages in Moodle, browsing to the page in Moodle for the plugin and then following the 'Moodle Docs for this page' link. This will result in a link of the form docs.moodle.org/en/mod/pluginname. The page can then be redirected to docs.moodle.org/en/Plugin_name by adding the text #redirect [[Plugin_name]].

What should the documentation include?

Example infobox: Stamp collection module

*New*: Copy and complete the following template code to obtain an infobox listing details of the plugin:

{{Infobox plugin
|type = Enter the plugin type e.g. activity, block, filter
|entry = Enter the plugins directory link
|tracker = Enter the bug tracker URL
|discussion = Enter the link to the forum or discussion thread
|maintainer = [[User:Maintainer name|Maintainer name]]
|float = Enter left or right to make the box float to that side (optional)
}}

Note: If there is not yet a discussion thread about your plugin, please create one in the General plugins forum.

Note: Please make sure that the page linked in 'User:Maintainer name|Maintainer name' actually has your relevant details (profile), or a link to an existing profile in Moodle or elsewhere.

The documentation may also include

  • A features overview with screenshots or videos.
  • Installation instructions

Plugin documentation examples: en:Stamp collection module, en:Profile switches.

Which version of the user docs should the documentation be added to?

Plugin documentation should be added to the most recent version wiki in which the plugin works, for example if the plugin works in Moodle 3.4, it should be added to the Moodle 3.4 docs wiki.

I need help!

If any of the above sounds too complicated, please don't worry - just email Moodle Docs wiki admin Helen (helen@moodle.org) who will be happy to help you :-) (Restoring and redirecting pages etc. are quick and easy for a wiki admin to do!)

See also