Actions

Help33

Difference between revisions of "Help screens styleguide"

From Joomla! Documentation

m (saving to preserve changes while updating)
m (Notes for help screen editors: clean up)
 
(9 intermediate revisions by 4 users not shown)
Line 9: Line 9:
 
   
 
   
 
=Help Screen Page Layout=
 
=Help Screen Page Layout=
 +
 +
==Description==
 +
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.
  
 
==How to Access==
 
==How to Access==
Line 17: Line 22:
 
|  
 
|  
 
*Click the Article Manager icon in the [[Help30:Site_Control_Panel|Control Panel]]  
 
*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'''''.
+
*Select '''Content Article Manager''' 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.
+
*Click the '''Article''' link while viewing the [[Help30:Components Content Categories|Category Manager]] or [[Help30:Content_Featured_Articles|Featured Articles]] in the left, upper sidebar.
 
|}
 
|}
  
Line 24: Line 29:
 
:* 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.
+
:* 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==
+
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 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.
 +
 
 +
==Form Fields (by Tab)==
 +
===Details Tab===
 +
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]].
 +
===Other Tab Types===
 +
If fields are grouped into fieldsets or tabs then group the fields under sub-headings.
 +
 
 +
==Column Headers==
 +
This section should only be included on help screens that describe back-end manager screens; that is, where you have a list of items being shown.  This section should describe each of the list columns.
 +
 
 +
==List Filters==
 +
This section should only be included on help screens that describe back-end manager screens; that is, where you have a list of items being shown.  This section should describe how to use the list filters to filter the contents of the screen. See [[Screen.content.15#List_Filters]] for example from 1.5.
 +
 
 +
==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.
  
 
==Toolbar==
 
==Toolbar==
Line 56: Line 73:
 
where <iconslist> is a '-' separated list of the toolbar legends.  Each word should be capitalised, spaces and '&' removed.
 
where <iconslist> is a '-' separated list of the toolbar legends.  Each word should be capitalised, spaces and '&' removed.
 
For example: Help30-Toolbar-New-Edit-Delete-Options-Help.png
 
For example: Help30-Toolbar-New-Edit-Delete-Options-Help.png
 
==List Filters==
 
This section should only be included on help screens that describe back-end manager screens; that is, where you have a list of items being shown.  This section should describe how to use the list filters to filter the contents of the screen. See [[Screen.content.15#List_Filters]] for example from 1.5.
 
 
==Column Headers==
 
This section should only be included on help screens that describe back-end manager screens; that is, where you have a list of items being shown.  This section should describe each of the list columns.
 
 
==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]].
 
 
If fields are grouped into fieldsets or tabs then group the fields under sub-headings.
 
 
==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]].
 
 
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.
 
  
 
==Batch Process==
 
==Batch Process==
Line 81: Line 82:
 
==Related Information==
 
==Related Information==
 
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=
Line 115: Line 115:
 
</noinclude>
 
</noinclude>
  
<noinclude>{{cathelp|3.0,3.1}}</noinclude>
+
<noinclude>{{cathelp|3.0,3.1,3.2,3.3}}</noinclude>

Latest revision as of 11:28, 30 April 2014

Contents

Introduction

Return to Joomla! 3.3 Help Screen Wiki Page

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.

Info non-talk.png
General Information

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.

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.

Help Screen Page Layout

Description

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

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.

Here's an example:

  • Click the Article Manager icon in the Control Panel
  • Select Content → Article Manager from the drop-down menu of the Joomla! Administrator Panel.
  • Click the Article link while viewing the Category Manager or Featured Articles in the left, upper sidebar.
*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.
  • 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(  ), This pointing  at that see the {{rarr}} template for use. It was designed to make help screen How to Access instructions easy to write.

Screenshot

Screenshot showing the overall look of the screen.

*Notes:
  • 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 for help screens, Help33-<menu system path in lowercase separated by dashes>-screen.png. For example, a screenshot of the Article Manager screen would be [[Image:Help33-content-article-manager-screen.png]].
  • You can use either .png or .jpg files.

Form Fields (by Tab)

Details Tab

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.

Other Tab Types

If fields are grouped into fieldsets or tabs then group the fields under sub-headings.

Column Headers

This section should only be included on help screens that describe back-end manager screens; that is, where you have a list of items being shown. This section should describe each of the list columns.

List Filters

This section should only be included on help screens that describe back-end manager screens; that is, where you have a list of items being shown. This section should describe how to use the list filters to filter the contents of the screen. See Screen.content.15#List_Filters for example from 1.5.

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

Toolbar

Obviously, this section should only be included on help screens where a toolbar is present.

Describes the available buttons and their associated functions. Use chunks here because many will be the same for different screens. Best to provide a picture of the toolbar.

The first word should always be a verb and, unless it is an irregular verb, it should also end in the letter "s". This means you should structure the description as if you are using the word "this" as the subject, but leave the subject out of the sentence. This will make the sentence actually a sentence fragment. For instance:

  • Instead of "To find buried treasures, click this button."
    • Say, "Finds buried treasures."
  • Instead of "You can click this button to insert a picture of John Stamos into the current document."
    • Say, "Inserts a picture of John Stamos."
  • Instead of "Inform yourself that a picture of John Stamos is the same thing as a buried treasure."
    • Say, "Informs you that a picture of John Stamos is the same thing as buried treasure."

Since many toolbars are the same across multiple screens, the image filenaming convention for toolbars is aimed at making it easy to re-use toolbar images wherever possible. Toolbar images should follow this naming convention: Help<version>-Toolbar-<iconslist>.png where <iconslist> is a '-' separated list of the toolbar legends. Each word should be capitalised, spaces and '&' removed. For example: Help30-Toolbar-New-Edit-Delete-Options-Help.png

Batch Process

This section should only be included on help screens where the screen has a batch process feature. For example, see Help30:Components Banners Categories.

Quick Tips

As the name suggests, this section should include tips, hints, suggestions that can assist a user in performing tasks involving the screen.

Related Information

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

  • Layout of a typical Help Screen
  • Overview of Help screen chunks
    For usage information and examples see the following templates:
  • Content editors
  • Did you notice a mistake or do think it's useful to add some extra information? You're welcome to modify the Help Screen. Please change the status of the modified Help Screen after you modified it:
    • Is the status at the moment 'Ready' or 'To be moved'? Change it to 'Modified by [name]' (replace [name] for your username at the Joomla! Docs Wiki)
    • Is the status at the moment 'To be reviewed'? You don't have to change the status in that case.
  • Image file naming convention:
    • help16-[menu system path separated by dashes]-[screenElementType].png,jpg
      • Replace [menu system path separated by dashes] with the names of the menu items that you would need to select to get to the item you are taking a screenshot of. Separate menu items with a dash ( - ) and if the menu item name has more than one word in it, then separate the words with an underscore ( _ ). Do not use spaces in your file name. Replace spaces with the underscore ( _ ) character.
      • Replace [screenElementType] with the type of the screen element that your picture contains. Screen element types are:
        • screen - This is a screenshot of the entire menu item
        • toolbar - This is a picture of the menu item's tool bar.
        • menu - This is a picture of the menu item's menu bar.
        • NOTE: As more screen element types are needed, add them to this style guide so that help documentation developers can refer to this guide and stay consistent.
      • Examples using the image naming convention:
        • 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

<headertabs/>