Note:

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

Guideline template: Difference between revisions

From MoodleDocs
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 guidelines (patterns) on pattern writing, I have referred to relevant sections in [http://www.hillside.net/patterns/writing/patternwritingpaper.htm A Pattern Language for Pattern Writing].  
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).  


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].
{{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.


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]
Example: [[Progressive_Disclosure#Problem|Progressive disclosure#Problem]]


{{Work in progress|info=<br /><br />'''This is a guideline template for the [[Usability/Improve_Moodle_User_Experience_Consistency]] project. '''}}
Further information: [http://www.hillside.net/patterns/writing/patterns.htm#B.1 Mandatory Elements Present]
== Problem ==
Describe the problem this guideline/pattern 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 / Pattern: [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.  


== Context ==
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.
: The circumstances in which the problem is being solved imposes constraints on the solution. The '''context''' is often described via a "situation" rather than stated explicitly. Sometimes, the context is described in terms of patterns <nowiki>[guidelines]</nowiki> that have already been applied. The relative importance of the '''forces''' (those that need to be optimized at the expense of others) is determined by the context. - [http://www.hillside.net/patterns/writing/patterns.htm#B.1 Mandatory Elements Present]


Describe the situation/context a developer is in when they need this guideline. Do not repeat information already in the problem section.
Example: [[Progressive_Disclosure#Context]]


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 ==


: Forces: The often contradictory considerations that must be taken into account when choosing a solution to a problem. The relative importance of the forces (those that need to be optimized at the expense of others) is implied by the context. - [http://www.hillside.net/patterns/writing/patterns.htm#B.1 Mandatory Elements Present]
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.


List all the points that appear in the Context that affect the decision. 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 it [http://www.hillside.net/patterns/writing/patterns.htm#B.4 Single-Pass Readable].
Further information: [http://www.hillside.net/patterns/writing/patterns.htm#B.1 Mandatory Elements Present]


'''Example: '''
'''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"  


'''becomes'''
'''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

Image 1: Screenshot demonstrating the subject of the guideline, including the different states or the sequence included in a single image

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

Image 1: Screenshot demonstrating the example of the guideline, including the different states or the sequence included in a single image

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

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