Help strings: Difference between revisions
Helen Foster (talk | contribs) (discussion link) |
David Mudrak (talk | contribs) m (Added info about _desc strinng and Markdown syntax) |
||
Line 2: | Line 2: | ||
{{Infobox Project | {{Infobox Project | ||
|name = 2.0 help strings | |name = 2.0 help strings | ||
|state = | |state = In progress | ||
|tracker = MDL-21695 | |tracker = MDL-21695 | ||
|discussion = [http://moodle.org/mod/forum/discuss.php?d=149220 Help file integration in php lang files] | |discussion = [http://moodle.org/mod/forum/discuss.php?d=149220 Help file integration in php lang files] | ||
Line 16: | Line 16: | ||
* ''stringname_help'' | * ''stringname_help'' | ||
* ''stringname_link'' (optional string naming a path in Moodle docs, only if required, calculated just like the link in the footer to go to the right language etc, and shown after the help text in the popup as a link, possibly with an icon, to "More info...") | * ''stringname_link'' (optional string naming a path in Moodle docs, only if required, calculated just like the link in the footer to go to the right language etc, and shown after the help text in the popup as a link, possibly with an icon, to "More info...") | ||
* ''stringname_desc'' (to be used as a description of admin settings. If this one is missing, the stringname_help will be displayed) | |||
For example: | For example: | ||
$string['submissionsize'] = 'Submission size'; | $string['submissionsize'] = 'Submission size'; | ||
$string['submissionsize_help'] = 'Blah blah blah some useful text using | $string['submissionsize_help'] = 'Blah blah blah some useful text, optionally using Markdown syntax'; | ||
$string['submissionsize_link'] = 'mod/workshop/submission'; | $string['submissionsize_link'] = 'mod/workshop/submission'; | ||
$string['submissionsize_desc'] = 'Default value for submission size. This value will be pre-filled and can be blah blah ...'; | |||
Note: The ''stringname_link'' strings don't need to be in the translator interface. | Note: The ''stringname_link'' strings don't need to be in the translator interface. | ||
Line 27: | Line 29: | ||
==Help string formatting== | ==Help string formatting== | ||
Help string text | Help string text should be short and simple - two small paragraphs maximum (150 words?) with no headings, no links, no bold, no tables etc. | ||
[[Markdown]] can be used for some formatting. It is recommended to stick on paragraphs and lists only. | |||
* paragraphs - new lines | * paragraphs - new lines | ||
* bullet points - * | * bullet points - * | ||
==Words for roles== | ==Words for roles== |
Revision as of 12:11, 10 May 2010
Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.
2.0 help strings | |
---|---|
Project state | In progress |
Tracker issue | MDL-21695 |
Discussion | Help file integration in php lang files |
Assignee | Helen Foster |
Moodle 2.0
In Moodle 2.0, help files will be converted to strings.
String names
Help strings names will start with the string name of the setting to which they apply, so that they are kept together in the language file.
- stringname
- stringname_help
- stringname_link (optional string naming a path in Moodle docs, only if required, calculated just like the link in the footer to go to the right language etc, and shown after the help text in the popup as a link, possibly with an icon, to "More info...")
- stringname_desc (to be used as a description of admin settings. If this one is missing, the stringname_help will be displayed)
For example:
$string['submissionsize'] = 'Submission size'; $string['submissionsize_help'] = 'Blah blah blah some useful text, optionally using Markdown syntax'; $string['submissionsize_link'] = 'mod/workshop/submission'; $string['submissionsize_desc'] = 'Default value for submission size. This value will be pre-filled and can be blah blah ...';
Note: The stringname_link strings don't need to be in the translator interface.
Help string formatting
Help string text should be short and simple - two small paragraphs maximum (150 words?) with no headings, no links, no bold, no tables etc.
Markdown can be used for some formatting. It is recommended to stick on paragraphs and lists only.
- paragraphs - new lines
- bullet points - *
Words for roles
The following words should be used in the en help strings whenever it is necessary to refer to people with particular roles in a generic sense.
- Participants - all people with a role
- Teachers - people with some sort of a facilitation/editing role
- Students - people primarily there to learn
- Users - people across the site
(Martin Dougiamas 16:13, 20 April 2010 (UTC): I'm not entirely comfortable with this choice even though I just re-confirmed it, as I'd prefer to be using words like facilitator/moderator to subtly and continually promote a less transmissionist pedgagogy and I know many Moodle users would agree. However, I think these terms are far more commonly used in the community and in discussion, and from the point of view that we need to build a consistent system for usability they are less distracting and better for documentation.)