Guideline template: Difference between revisions
mNo edit summary |
(This page will not be migrated to new devdocs) |
||
(14 intermediate revisions by one other user not shown) | |||
Line 1: | Line 1: | ||
{{Template:WillNotMigrate}} | |||
[[ Moodle User Interface Guidelines|Moodle User Interface Guidelines]] > '''Guideline template''' | [[ Moodle User Interface Guidelines|Moodle User Interface Guidelines]] > '''Guideline template''' | ||
This guideline template acts as instructions on how to write a guideline. It describes what should appear under each heading. For relevant | This guideline template acts as instructions on how to write a guideline. It describes what should appear under each heading. For relevant advice on writing these, I have referred to relevant sections in [http://www.hillside.net/patterns/writing/patternwritingpaper.htm A Pattern Language for Pattern Writing] (they talk about patterns, but the term guideline is used instead in the Moodle UI Guidelines). | ||
{{Work in progress|forumurl=http://moodle.org/mod/forum/discuss.php?d=126884|info=<br /><br />'''This is a guideline template for a [[Moodle_User_Interface_Guidelines|Moodle Interface Guideline]]. Comments: [http://moodle.org/mod/forum/discuss.php?d=126884 developer forum thread] '''}} | |||
== Problem == | |||
Describe the problem this guideline is a solution to. Imagine the situation in which a developer is when they need this guideline, and describe it as briefly as possible, but still being detailed enough to enable the reader to recognize if this guideline is what they need or not. Ensure the problem is also kept separate from the constraints of the Solution. | |||
Example: [[Progressive_Disclosure#Problem|Progressive disclosure#Problem]] | |||
Further information: [http://www.hillside.net/patterns/writing/patterns.htm#B.1 Mandatory Elements Present] | |||
== Context == | |||
Describe the situation/context a developer is in when they need this guideline. Do not repeat information already in the problem section. | |||
UI design problems are always being solved in a specific context, or situation. Sometimes, you can describe the context by mentioning the <nowiki>guidelines</nowiki> that have already been applied. It depends on the context which forces (see the following heading) are prioritized while selecting a solution. | |||
Example: [[Progressive_Disclosure#Context]] | |||
Further information: [http://www.hillside.net/patterns/writing/patterns.htm#B.1 Mandatory Elements Present] | |||
== Forces: factors that affect selection == | == Forces: factors that affect selection == | ||
List all the consideration that appear that affect choosing the solution. These often appear as points for or against the Solution. Formulate them so that they are independent of the solution and just relate to the problem. This is to make the guideline [http://www.hillside.net/patterns/writing/patterns.htm#B.4 Single-Pass Readable]. | |||
Forces: The often contradictory considerations that must be taken into account when choosing a solution to a problem. | |||
Further information: [http://www.hillside.net/patterns/writing/patterns.htm#B.1 Mandatory Elements Present] | |||
''' | '''For example, ''' while writing the guideline for progressive disclosure, the following force was identified: | ||
"Administrators need to 'lock' the show/hide button [of progressive disclosure] because on some sites the functionality is needed by everybody" | : "Administrators need to 'lock' the show/hide button [of progressive disclosure] because on some sites the functionality is needed by everybody" | ||
''' | '''To make it independent of the solution''', I included only the force (problematic consideration) in it here, and moved the solution (locking the show/hide button) into the Solution part of the guideline: | ||
"Some functionality that is rarely needed on some Moodle sites may be always-required basic functionality on other sites." | : "Some functionality that is rarely needed on some Moodle sites may be always-required basic functionality on other sites." | ||
[http://www.hillside.net/patterns/writing/patterns.htm#B.3 Visible Forces] | Further information: [http://www.hillside.net/patterns/writing/patterns.htm#B.3 Visible Forces] | ||
== Solution == | == Solution == | ||
Line 44: | Line 47: | ||
If further explanation of the different aspects is required, add subheadings for them. | If further explanation of the different aspects is required, add subheadings for them. | ||
== (Optional) Common mistakes == | == (Optional) Common mistakes == | ||
Line 66: | Line 68: | ||
'''Further examples and code samples: (link to) <nowiki>Development:[GuidelineName] Examples and Code Samples</nowiki>''' | '''Further examples and code samples: (link to) <nowiki>Development:[GuidelineName] Examples and Code Samples</nowiki>''' | ||
== (Optional) Related guidelines == | |||
If some other guideline does something similar and could be considered in the same situation, list them here. | |||
== (Optional) Related issues in the tracker == | == (Optional) Related issues in the tracker == | ||
Line 79: | Line 83: | ||
Pattern: [http://www.hillside.net/patterns/writing/patterns.htm#B.2 Optional Elements When Helpful] | Pattern: [http://www.hillside.net/patterns/writing/patterns.htm#B.2 Optional Elements When Helpful] | ||
= Additional information to supplement the Guideline template = | |||
Important points to consider that dictate much of the form of a guideline include: [http://www.hillside.net/patterns/writing/patterns.htm#B.4 Single-Pass Readable], [http://www.hillside.net/patterns/writing/patterns.htm#B.5 Skippable Sections] and [http://www.hillside.net/patterns/writing/patterns.htm#B.5 Findable Sections]. | |||
See also: [http://www.hillside.net/patterns/writing/patterns.htm#C Pattern Naming and Referencing Patterns], [http://www.hillside.net/patterns/writing/patterns.htm#D Patterns For Making Patterns Understandable] | |||
= Shortened Guideline Template = | |||
[[ Moodle User Interface Guidelines|Moodle User Interface Guidelines]] > '''Guideline template''' | |||
{{Work in progress|forumurl=http://moodle.org/mod/forum/discuss.php?d=126884|info=<br /><br />'''This is a guideline for a [[Moodle_User_Interface_Guidelines|Moodle Interface Guideline]]. Comments: [http://moodle.org/mod/forum/discuss.php?d=126884 developer forum thread] '''}} | |||
== Problem == | |||
== Context == | |||
== Forces: factors that affect selection == | |||
== Solution == | |||
== (Optional) Common mistakes == | |||
== Examples and implementation == | |||
=== Example title === | |||
== (Optional) Related guidelines == | |||
== (Optional) Related issues in the tracker == | |||
== (Optional) Further information / Sources == |
Latest revision as of 14:37, 27 May 2022
Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable. |
Moodle User Interface Guidelines > Guideline template
This guideline template acts as instructions on how to write a guideline. It describes what should appear under each heading. For relevant advice on writing these, I have referred to relevant sections in A Pattern Language for Pattern Writing (they talk about patterns, but the term guideline is used instead in the Moodle UI Guidelines).
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.
This is a guideline template for a Moodle Interface Guideline. Comments: developer forum thread
Problem
Describe the problem this guideline is a solution to. Imagine the situation in which a developer is when they need this guideline, and describe it as briefly as possible, but still being detailed enough to enable the reader to recognize if this guideline is what they need or not. Ensure the problem is also kept separate from the constraints of the Solution.
Example: Progressive disclosure#Problem
Further information: Mandatory Elements Present
Context
Describe the situation/context a developer is in when they need this guideline. Do not repeat information already in the problem section.
UI design problems are always being solved in a specific context, or situation. Sometimes, you can describe the context by mentioning the guidelines that have already been applied. It depends on the context which forces (see the following heading) are prioritized while selecting a solution.
Example: Progressive_Disclosure#Context
Further information: Mandatory Elements Present
Forces: factors that affect selection
List all the consideration that appear that affect choosing the solution. These often appear as points for or against the Solution. Formulate them so that they are independent of the solution and just relate to the problem. This is to make the guideline Single-Pass Readable.
Forces: The often contradictory considerations that must be taken into account when choosing a solution to a problem.
Further information: Mandatory Elements Present
For example, while writing the guideline for progressive disclosure, the following force was identified:
- "Administrators need to 'lock' the show/hide button [of progressive disclosure] because on some sites the functionality is needed by everybody"
To make it independent of the solution, I included only the force (problematic consideration) in it here, and moved the solution (locking the show/hide button) into the Solution part of the guideline:
- "Some functionality that is rarely needed on some Moodle sites may be always-required basic functionality on other sites."
Further information: Visible Forces
Solution
Illustrate the solution so that it is understood as quickly as possible.
Explain how the forces are alleviated by the solution. Explain the ultimate benefits/goals reached by applying the solution, and how the solution's different aspects help reach them.
If further explanation of the different aspects is required, add subheadings for them.
(Optional) Common mistakes
If there are common scenarios where this guideline is broken, list them here, explain why they are wrong and how to solve these issues.
Examples and implementation
As per A Pattern Language for Pattern writing, there should be as few examples here as possible. List one or two here and link to a separate Development:[GuidelineName] Examples and Code Samples page.
Patterns:
Example title
Refer to how the points in the Solution have been fulfilled
Further examples and code samples: (link to) Development:[GuidelineName] Examples and Code Samples
(Optional) Related guidelines
If some other guideline does something similar and could be considered in the same situation, list them here.
(Optional) Related issues in the tracker
- MDL-99999999 A ticket for fixing something in Moodle to be in accordance with this guideline
- CREATE: ticket not yet created in the tracker
- To be decided: description of issue in Moodle that are in conflict with this guideline but a clear decision has not been reached what should be done about it
Pattern: Optional Elements When Helpful
(Optional) Further information / Sources
Link to sources for this guideline. If you quote from these sources, add a link to this section from the earlier sections with the author name.
Pattern: Optional Elements When Helpful
Additional information to supplement the Guideline template
Important points to consider that dictate much of the form of a guideline include: Single-Pass Readable, Skippable Sections and Findable Sections.
See also: Pattern Naming and Referencing Patterns, Patterns For Making Patterns Understandable
Shortened Guideline Template
Moodle User Interface Guidelines > Guideline template
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.
This is a guideline for a Moodle Interface Guideline. Comments: developer forum thread