Difference between revisions of "MoodleDocs:Guidelines for contributors"

Jump to: navigation, search

Note: You are currently viewing documentation for Moodle 2.7. Up-to-date documentation for the latest stable version of Moodle may be available here: Guidelines for contributors.

(Add something about emerging page style types :))
m (French link)
 
(31 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{Help}}
+
{{Help}}You are welcome to contribute to Moodle Docs. Find something that can be improved, either in content, grammar or formatting, and fix it! Note: You will need to [[Special:Userlogin|login]] to edit pages.
 +
 
 
==Introduction==
 
==Introduction==
* You are welcome to contribute to Moodle Docs. Find something that can be improved, either in content, grammar or formatting, and fix it!
+
 
* If you've not done so already, please [[Special:Userlogin|login]].
 
 
* Please note that all contributions are released here under [[License|GNU General Public License]].
 
* Please note that all contributions are released here under [[License|GNU General Public License]].
* From Moodle 1.6 onwards, every page in Moodle has a link to a corresponding page in Moodle Docs. You can see this on [http://moodle.org moodle.org] and, from an administrator's perspective, on the [http://demo.moodle.com/ Moodle demo site].
+
* Every page in Moodle has a link to a corresponding page in Moodle Docs. You can see this on [http://moodle.org moodle.org] and, from an administrator's perspective, on the [http://demo.moodle.net/ Moodle demo site].
* Please note that the [http://moodle.org/help.php?file=index.html Moodle help files] will remain in each language pack and so their text need not be included in this documentation, though a small amount of duplicate information is ok.
 
 
* You are encouraged to illustrate documentation with screenshots. Please refer to the [[MoodleDocs:Style guide|style guide]] for further information.
 
* You are encouraged to illustrate documentation with screenshots. Please refer to the [[MoodleDocs:Style guide|style guide]] for further information.
* There are tags you can place to ask for [[MoodleDocs:Style_guide#MoodleDoc_editing_tags|editing help]] from other contributors. These include requests for page [[MoodleDocs:Deletion|deletion]], [[MoodleDocs:Update|updating]] and [[MoodleDocs:Stub|stub notations]].
+
* See [[MoodleDocs:Templates]] for ways of asking for editing help from other contributors.
  
 
==Creating new pages==
 
==Creating new pages==
  
* You are welcome to create pages for additional documentation. Simply type the name of your new page between double brackets <code><nowiki>[[New page name]]</nowiki></code> on an existing page and follow the link to start editing the new page. Alternatively, you may type in your browser address bar: <code><nowiki>https://docs.moodle.org/en/New_page_name</nowiki></code> (i.e. replace spaces in the new page name with underscores).
+
* You are welcome to create pages for additional documentation about Moodle. Simply type the name of your new page between double brackets <code><nowiki>[[New page name]]</nowiki></code> on an existing page and follow the link to start editing the new page. Alternatively, you may type in your browser address bar: <code><nowiki>https://docs.moodle.org/en/New_page_name</nowiki></code> (i.e. replace spaces in the new page name with underscores).
 
* Please choose a short name and capitalize the first word only (with a few exceptions, such as the word ''Moodle'').
 
* Please choose a short name and capitalize the first word only (with a few exceptions, such as the word ''Moodle'').
* New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[Development:New page name]]</nowiki></code>.
 
 
* Please follow the [[MoodleDocs:Style guide|style guide]]. If you categorize new pages it can make it easier for users to find, but the important thing is to put good content into the page.  
 
* Please follow the [[MoodleDocs:Style guide|style guide]]. If you categorize new pages it can make it easier for users to find, but the important thing is to put good content into the page.  
 
* Page titles may be changed in the future by redirecting/moving pages, as part of documentation restructuring.
 
* Page titles may be changed in the future by redirecting/moving pages, as part of documentation restructuring.
  
==Page styles==
+
==Inter-language linking==
As Moodle Docs has grown over time, several general page style types with their own informal guidelines have emerged.  As you look at pages you will probably recognize some of these.  The basic rule is that if there is no page content, there is nothing to find and certainly nothing for the community to edit and consider.  Thusly, please feel free to add content.
 
  
*'''General pages''' - the most common and most varied. The [[MoodleDocs:Style guide]] gives a good idea of the potential.
+
* Inter-language links between pages in different languages may be added by typing, for example, <code><nowiki>[[es:Corresponding page title in Spanish]]</nowiki></code> in the English MoodleDocs, or <code><nowiki>[[en:Corresponding page title in English]]</nowiki></code> in the [[:es:Portada|Spanish MoodleDocs]], at the bottom of the page, below the category link. Inter-language links will appear automatically in the "In other languages" block.
  
*'''Introduction pages'''.  These serve almost as table of contents on a subject to pages with more detailed information. Several techniques are used.  Some times links are placed by before bullets (using the * in edit mode). Or short sentences maybe used to give context for the embedded page links. Some of the major subject introduction pages are protected.
+
== Page comments ==
  
*'''FAQ pages'''. Links to these pages from Moodle.org forums started to appear in 2008. These are similar to introduction pages. In this kind of page, each heading has something about a frequently asked question, the typical answer is short.  The answer provides links to pages, or links to a specific page section that should expand the answer to the question. It is OK to put in a particular item that may have frustrated you, along with a description of the solution.  Like anything in Moodle Docs it maybe edited.
+
* For comments about a particular page, and/or short discussions, please use the corresponding talk page (click on the page comments tab). Please sign and date your talk page contribution by typing four tildes <nowiki>~~~~</nowiki>. There's also a handy button for signing in the toolbar of the editing field: [[Image:Signature Icon.png]]
  
*'''Contributed code pages'''. These tend to have links to the moodle.org download database, to the forum that discusses issues. Of course there will be a brief description of its purpose, a list of features, maybe some hints about installing and useful settings.  
+
* For longer discussions about the documentation, please post on moodle.org in the [http://moodle.org/mod/forum/view.php?id=7135 Moodle community sites forum].
 
 
==Inter-language linking==
 
  
* You are welcome to add inter-language links between pages in different languages. Simply type, for example, <code><nowiki>[[es:Corresponding page title in Spanish]]</nowiki></code> in the English MoodleDocs, or <code><nowiki>[[en:Corresponding page title in English]]</nowiki></code> in the [[:es:Portada|Spanish MoodleDocs]], at the bottom of the page, below the category link. Inter-language links will appear automatically in the "In other languages" block. With the exception of English, only related languages are interlinked. (If you feel that a related language is not included contact the Docs administrator).
+
* If you find an unsigned comment you can use the Template:Unsigned like so <nowiki>{{Unsigned|Username}}</nowiki> which will show as <small>(''The preceding comment was added by'' [[User:Username]])</small>
  
==Moodle version templates==
+
==Page protection==
 
 
* When adding documentation about a new feature, please add a Moodle version template by typing, for example, <code><nowiki>{{Moodle 1.9}}</nowiki></code>.
 
* In addition to highlighting differences in Moodle versions, Moodle version templates automatically categorize articles into version categories, for example [[:Category:Moodle 1.9]].
 
* Templates for Moodle versions no longer available from [http://download.moodle.org/ Moodle downloads] can be removed and replaced with ordinary text, for example "From Moodle 1.5 onwards, ...".
 
  
== Page comments ==
+
* Certain pages, such as the [[Table of Contents]], are protected from editing. Please use the page comments for suggesting additional content or other changes.
  
* For comments about a particular page, and/or short discussions, please use the corresponding talk page (click on the page comments tab). Please sign and date your talk page contribution by typing four tildes <nowiki>~~~~</nowiki>.
+
==See also==
* For longer discussions about the documentation, please use the Using Moodle [http://moodle.org/mod/forum/view.php?id=5838 Documentation forum].
 
  
==Page protection==
+
*[[Moodle documentation FAQ]]
* Some pages are protected from editing. For these pages, try contributing via the associated talk page.
+
*[http://moodle.org/mod/forum/view.php?id=7135 Moodle community sites forum].
**Tip: Copy the contents of a protected page, paste it in a new page, then edit the new page. On the new page's "page comment" tab give reasons for the edit. Then on the protected page's "Page comment" tab, call attention to the new page with a link and a summary of your reasons for change.
 
* For a list of protected pages, see [[:Category:Protected pages]].
 
  
 
[[Category:MoodleDocs|Guidelines for contributors]]
 
[[Category:MoodleDocs|Guidelines for contributors]]
  
 +
[[ca:MoodleDocs:Recomanacions_als_ajudants]]
 +
[[de:Hinweise für Moodle Docs Autoren]]
 
[[es:MoodleDocs:Normas para colaboradores]]
 
[[es:MoodleDocs:Normas para colaboradores]]
[[fr:MoodleDocs:Recommandations pour contributeurs]]
+
[[fr:Contribution à la documentation]]
 
[[ja:MoodleDocs:寄稿のガイドライン]]
 
[[ja:MoodleDocs:寄稿のガイドライン]]
[[ru:MoodleDocs:Путеводитель_для_разработчиков_документации]]
 
[[zh:MoodleDocs:贡献者指引]]
 
[[sv:MoodleDocs:Riktlinjer för bidrag]]
 

Latest revision as of 09:08, 9 February 2016


You are welcome to contribute to Moodle Docs. Find something that can be improved, either in content, grammar or formatting, and fix it! Note: You will need to login to edit pages.

Introduction

  • Please note that all contributions are released here under GNU General Public License.
  • Every page in Moodle has a link to a corresponding page in Moodle Docs. You can see this on moodle.org and, from an administrator's perspective, on the Moodle demo site.
  • You are encouraged to illustrate documentation with screenshots. Please refer to the style guide for further information.
  • See MoodleDocs:Templates for ways of asking for editing help from other contributors.

Creating new pages

  • You are welcome to create pages for additional documentation about Moodle. Simply type the name of your new page between double brackets
    [[New page name]]
    on an existing page and follow the link to start editing the new page. Alternatively, you may type in your browser address bar:
    https://docs.moodle.org/en/New_page_name
    (i.e. replace spaces in the new page name with underscores).
  • Please choose a short name and capitalize the first word only (with a few exceptions, such as the word Moodle).
  • Please follow the style guide. If you categorize new pages it can make it easier for users to find, but the important thing is to put good content into the page.
  • Page titles may be changed in the future by redirecting/moving pages, as part of documentation restructuring.

Inter-language linking

  • Inter-language links between pages in different languages may be added by typing, for example,
    [[es:Corresponding page title in Spanish]]
    in the English MoodleDocs, or
    [[en:Corresponding page title in English]]
    in the Spanish MoodleDocs, at the bottom of the page, below the category link. Inter-language links will appear automatically in the "In other languages" block.

Page comments

  • For comments about a particular page, and/or short discussions, please use the corresponding talk page (click on the page comments tab). Please sign and date your talk page contribution by typing four tildes ~~~~. There's also a handy button for signing in the toolbar of the editing field: Signature Icon.png
  • If you find an unsigned comment you can use the Template:Unsigned like so {{Unsigned|Username}} which will show as (The preceding comment was added by User:Username)

Page protection

  • Certain pages, such as the Table of Contents, are protected from editing. Please use the page comments for suggesting additional content or other changes.

See also