Actions

Help33

Difference between revisions of "Help screens styleguide"

From Joomla! Documentation

m (automatic version checking)
(Fix red links)
Line 1: Line 1:
{{RightTOC}}
+
=Introduction=
[[Help30:Help_screens|Return to Joomla! {{CurrentSTSVer|minor}} Help Screen Wiki Page]]
+
[[Help31:Help_screens|Return to Joomla! {{CurrentSTSVer|minor}} Help Screen Wiki Page]]
  
This is a work in progress and should be used as a guideline for creating help screens for Joomla 3.0. This offers consistency throughout the help screens to allow for easier navigation.  Feel free to add to this.
+
This is a work in progress and should be used as a guideline for creating Help screens for '''Joomla 3.x'''. The help screens which exist on the Joomla! Docs Wiki are being accessed by every Joomla! installation using the default help system. By following this styleguide, the Joomla! Project can offer consistency throughout the help screens to allow for easier navigation.
  
==How to Access==
+
{{notice|Please only use screenshots with a maximum width of 670px. While they may appear undersized on a wiki page, this prevents x-axis scrolling in the pop up window of the actual Joomla! administration view.}}
Each and every help screen should begin with a "How to access" section that gives the steps required to reach the screen that is being described. You might think this is redundant because you must be on that screen in order to have retrieved the help screen, but actually the help screens can be retrieved in a number of different ways.  For example, someone using a search engine to find out how to do something might come across a help screen on the wiki without ever having accessed the help system.
+
  
Here's an example:
+
If you have a question, please post in on the associated talk page of the help screen by clicking the '''''Discussion''''' tab at the top of the help screen page.
{| style="margin-left:50px"
+
|-
+
=Help Screen Page Layout=
|To access this screen:
+
* Select '''Extensions → Module Manager''' from the drop-down menus.
+
  
If there is more than one way to access the screen, list them all.  For example:
+
==How to Access==
 +
Each and every help screen should begin with a "'''How to access'''" section that gives the steps required to reach the screen that is being described.  This might be redundant because a user must be on the administrator screen in order to have retrieved the help screen. Remember, the help screens can be retrieved in a number of different ways.  For example, someone using a search engine to find out how to do something might come across a help screen on the wiki without ever having accessed the help system.
  
To access this screen you can either:
+
Here's an example:
* Click the '''Article Manager''' button in the [[Help30:Site Control Panel|Control Panel]], or
+
{| style="margin-left:50px; background:#fff; padding:5px;"
* Select '''Content Article Manager''' from the drop-down menus.
+
|
 +
*Click the Article Manager icon in the [[Help30:Site_Control_Panel|Control Panel]]  
 +
*Select '''Content → Article Manger''' from the drop-down menu of the '''''Joomla! Administrator Panel'''''.
 +
*Click the '''Article''' link while viewing the [[Help30:Components Content Categories|Cateogry Manager]] or [[Help30:Content_Featured_Articles|Featured Articles]] in the left, upper sidebar.
 
|}
 
|}
  
Notes:
+
: *Note:
* If the way to reach the screen is from another screen then the name of that screen should be a link to its help screen.
+
:* If the way to reach the screen is from another screen then the name of that screen should be a link to its help screen.
* You "click" on buttons, including toolbar buttons, but you "select" menu items.  Consistent use of this terminology should help users.
+
:* You "click" on buttons, including toolbar buttons, but you "select" menu items.  Consistent use of this terminology should help users.
 +
:* For ease of rendering the right arrow({{rarr}}), {{rarr|This pointing,at that}} see the {{tl|rarr}} template for use. It was designed to make help screen '''How to Access''' instructions easy to write.  
  
 
==Description==
 
==Description==
This goes into more detail about what the screen does.  There is no specific format to this section because the description should be in direct correlation with the purpose and functionality of the screen.  There may be subsections to the description that describe more specific details.  If the description is long then consider using bullet points to summarise it.
+
Each and every help screen should have a "'''Description'''" section. This goes into more detail about what the screen does and is used in help screen tables throughout this wiki. [[Menu_Management#Menu Management Help Screens|Here is an use example]].   
 +
 
 +
There is no specific format to this section because the description should be in direct correlation with the purpose and functionality of the screen.  There may be subsections to the description that describe more specific details.  Try to keep the description short and to the point, if the description is long then consider using bullet points to summarise it.
  
 
==Screenshot==
 
==Screenshot==
 
Screenshot showing the overall look of the screen.
 
Screenshot showing the overall look of the screen.
  
Notes:
+
: *Notes:
* Screenshot images should be no wider than 670 pixels so that they fit neatly in the popup help window size without horizontal scrolling.
+
:* Screenshot images should be no wider than 670 pixels so that they fit neatly in the popup help window size without horizontal scrolling.
* The filename should follow our standard naming conventions.  In this case it will be Help30-<menu system path in lowercase separated by dashes>-screen.png.  For example, <nowiki>[[Image:Help30-content-article manager-screen.png]]</nowiki> is the wiki markup for the screenshot of the Article Manager screen.
+
:* The filename should follow our [[JDOC:Image_naming_convention|standard naming conventions]] for help screens, '''{{NS:138}}-''<menu system path in lowercase separated by dashes>''-screen.png'''.  For example, a screenshot for the the screenshot of the Article Manager screen would be '''<nowiki>[[Image:</nowiki>{{NS:138}}<nowiki>-content-article-manager-screen.png]]</nowiki>'''.
* You can use either .png or .jpg files.
+
:* You can use either .png or .jpg files.
  
 
==Toolbar==
 
==Toolbar==
Line 60: Line 64:
  
 
==Form Fields==
 
==Form Fields==
This section should only be included on help screens that describe screens which include a form.  This includes all the add/edit screens, but also includes screens like [[Help30:Site Global Configuration]] and modal popups like [[Help30:Content Article Manager Options]].
+
This section should only be included on help screens that describe screens which include a form.  This includes all the add/edit screens, but also includes screens like [[Help30:Site Global Configuration]] and modal popups like [[Help31:Components Article Manager Options]].
  
 
If fields are grouped into fieldsets or tabs then group the fields under sub-headings.
 
If fields are grouped into fieldsets or tabs then group the fields under sub-headings.
  
 
==Options==
 
==Options==
This section should only be included on help screens where the screen has an Options toolbar button which opens a modal options sub-screen.  If there are many options and the help screen would become excessively long if they were to be described here, then link to a separate help screen with an "_Options" suffix.  For example, see [[Help30:Content Article Manager Options|Content Article Manager Options]].
+
This section should only be included on help screens where the screen has an Options toolbar button which opens a modal options sub-screen.  If there are many options and the help screen would become excessively long if they were to be described here, then link to a separate help screen with an "_Options" suffix.  For example, see [[Help31:Components_Article_Manager_Options|Components Article Manager Options]].
  
 
Since the Options modal screen is usually tabbed you should add a sub-section under this section for each tab.  For example, if there is a tab labelled "Editing Layout" then you should add a third-level heading of that name and within that sub-section you should describe each of the available fields.  You should start each sub-section with a screenshot of the appropriate Options panel.
 
Since the Options modal screen is usually tabbed you should add a sub-section under this section for each tab.  For example, if there is a tab labelled "Editing Layout" then you should add a third-level heading of that name and within that sub-section you should describe each of the available fields.  You should start each sub-section with a screenshot of the appropriate Options panel.
Line 78: Line 82:
 
Generally this should be a list of links to further or related information.  All links should be to pages on this wiki.  No external links without very good reason.
 
Generally this should be a list of links to further or related information.  All links should be to pages on this wiki.  No external links without very good reason.
  
==Notes for help screen editors==
+
 
 +
=Notes for help screen editors=
 
*[[Help screen layout|Layout of a typical Help Screen]]
 
*[[Help screen layout|Layout of a typical Help Screen]]
 
*Overview of [{{fullurl:Special:Allpages|namespace=136}} Help screen chunks]<br/>For usage information and examples see the following templates:
 
*Overview of [{{fullurl:Special:Allpages|namespace=136}} Help screen chunks]<br/>For usage information and examples see the following templates:
 
** {{tlx|colheader|Column name}} includes one of the ''Help screen column header XYZ'' chunks
 
** {{tlx|colheader|Column name}} includes one of the ''Help screen column header XYZ'' chunks
** {{[[Chunk30:colheader|Chunk30:colheader|Column name]]}} includes one of the ''Help screen column header XYZ'' chunks for version {{JVer|3.0}}
+
** {{[[Chunk30:colheader|Chunk30:colheader|Column name]]}} includes one of the ''Help screen column header XYZ'' chunks for version {{JVer|3.x}}
** [[Using_chunks_in_Joomla_help_screens|Using chunks in Joomla help screens]] includes instructions for using and creating colheader chunks {{JVer|3.0}}
+
** [[Using_chunks_in_Joomla_help_screens|Using chunks in Joomla help screens]] includes instructions for using and creating colheader chunks {{JVer|3.x}}
 
** {{tlx|toolbaricon|Action name}} is for ''Help screen toolbar XYZ''
 
** {{tlx|toolbaricon|Action name}} is for ''Help screen toolbar XYZ''
 
** {{tlx|cpanelicon|Icon name}} is for ''Help screen icon XYZ''
 
** {{tlx|cpanelicon|Icon name}} is for ''Help screen icon XYZ''
Line 104: Line 109:
 
**** A screenshot of the Extension Manager's "Discover" screen would be named: help16-extension_manager-discover-screen.png
 
**** A screenshot of the Extension Manager's "Discover" screen would be named: help16-extension_manager-discover-screen.png
 
**** A screenshot of the Extension Manager's "Discover" screen tool bar would be named: help16-extension_manager-discover-toolbar.png
 
**** A screenshot of the Extension Manager's "Discover" screen tool bar would be named: help16-extension_manager-discover-toolbar.png
 +
<headertabs/>
 
<noinclude>[[Category:Joomla! 3.0]]
 
<noinclude>[[Category:Joomla! 3.0]]
[[Category:Style guides|{{PAGENAME}}]]</noinclude>
+
[[Category:Style guides|{{PAGENAME}}]]
 +
[[Category:Joomla! 3.1]]
 +
</noinclude>
  
 
<noinclude>{{cathelp|3.0,3.1}}</noinclude>
 
<noinclude>{{cathelp|3.0,3.1}}</noinclude>

Revision as of 02:55, 11 June 2013