Difference between revisions of "Help screens styleguide"
From Joomla! Documentation
m (→Screenshot: update to section) |
(Several markup changes and some Words2Watch corrections.) |
||
(194 intermediate revisions by 9 users not shown) | |||
Line 1: | Line 1: | ||
− | + | <noinclude><languages /></noinclude> | |
− | [[ | + | __NOEDITSECTION__ |
+ | [[<translate> | ||
+ | <!--T:38--> | ||
+ | <tvar name=1>S:MyLanguage/{{NAMESPACE}}:Help_screens</tvar>|Return to Joomla <tvar name=2>{{CurrentSTSVer|minor}}</tvar> Help Screen Wiki Page | ||
+ | </translate>]] | ||
− | This | + | <translate> |
+ | <!--T:39--> | ||
+ | This should be used as a guideline for creating Help screens. 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. | ||
− | {{ | + | <!--T:40--> |
+ | If you have a question, please post in on the associated talk page of the help screen by clicking ''Actions<tvar name=1>{{rarr|size=1}}</tvar>Discussion'' buttons. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_Description_Header/<translate><!--T:116--> en</translate>}} | ||
+ | <translate> | ||
+ | <!--T:43--> | ||
+ | Every help screen should begin with a '''Description''' section. This goes into detail about what the screen does. [[<tvar name=1>S:MyLanguage/{{NAMESPACE}}:Menus_Menu_Manager</tvar>|Here is an use example]]. | ||
− | + | <!--T:44--> | |
− | + | 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 specific details. | |
− | |||
− | + | <!--T:144--> | |
− | + | Keep the description short and to the point. If the description is long, consider using bullet points to summarise it. | |
+ | </translate> | ||
+ | {{Chunk30:Help_screen_How_To_Access_Header/<translate><!--T:117--> en</translate>}} | ||
− | + | <translate> | |
− | + | <!--T:46--> | |
− | + | Every help screen should have a '''How to Access''' section listing 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. | |
− | |||
− | |||
− | |||
− | |||
− | : | + | <!--T:132--> |
− | + | Remember, the help screens can be retrieved in 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. | |
− | |||
− | |||
− | + | <!--T:47--> | |
− | + | Here is an example: | |
+ | </translate> | ||
+ | {{Chunk30:Help_screen_How_To_Access_By_Menu/en|Content,Articles}} | ||
− | + | <translate> | |
+ | <!--T:114--> | ||
+ | Example's chunks and parameters: | ||
+ | </translate> | ||
− | + | *<tt><nowiki>{{Chunk30:Help_screen_How_To_Access_By_Menu/<translate>en</translate>|<translate>Content,Articles</translate>}}</nowiki></tt>{{-}}[[S:MyLanguage/JDOC:Using_chunks_in_Joomla_help_screens|<translate><!--T:141--> Learn more about using chunks in Joomla help screens.</translate>]] | |
+ | |||
+ | <translate> | ||
+ | <!--T:50--> | ||
+ | Note: | ||
+ | |||
+ | <!--T:52--> | ||
+ | * You "click" on buttons, including toolbar buttons, but you "select" menu items. Consistent use of this terminology should help users. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_Screenshot_Header/<translate><!--T:118--> en</translate>}} | ||
+ | |||
+ | <translate> | ||
+ | <!--T:55--> | ||
Screenshot showing the overall look of the screen. | Screenshot showing the overall look of the screen. | ||
+ | </translate> | ||
− | + | {{notice|title=<translate><!--T:143--> General Information</translate>|<translate><!--T:56--> Please always use screenshots with <tvar name=1><tt><nowiki>|800px</nowiki></tt></tvar> in the code whenever they are large. This way any size can be added and it will help translators to be able to add transcreated images without having to notice the width.</translate>}} | |
− | |||
− | |||
− | |||
− | + | <translate> | |
− | + | <!--T:57--> | |
+ | Notes: | ||
− | + | <!--T:58--> | |
+ | * The filename should follow our [[#Image_naming_guidelines|Image naming guidelines]] for help screens. | ||
− | The | + | <!--T:60--> |
− | + | * The filename should always include a language code at the end of the name. For English, <tvar name=1><tt>-en</tt></tvar> is added. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | <!--T:61--> | |
− | + | * You can use either ''.png'' or ''.jpg'' files. | |
− | + | </translate> | |
− | + | {{Chunk30:Help_screen_Column_Header/<translate><!--T:119--> en</translate>}} | |
− | + | <translate> | |
− | This section should only be included on help screens that describe | + | <!--T:63--> |
+ | This section should only be included on help screens that describe Backend screens; that is, where you have a list of items being shown. This section should describe each of the list columns. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_Column_Filtering_Header/<translate><!--T:120--> en</translate>}} | ||
− | + | <translate> | |
− | + | <!--T:133--> | |
+ | This section describes the dropdown input fields above the column headers. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_Details_Header/<translate><!--T:128--> en</translate>}} | ||
− | + | <translate> | |
− | This section should only be included on help screens that describe screens which include a form. | + | <!--T:66--> |
+ | 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 such as [[<tvar name=1>{{NAMESPACE}}:Site_Global_Configuration</tvar>|Site Global Configuration]] and [[<tvar name=2>{{NAMESPACE}}:Components_Article_Manager_Options</tvar>|Article Options]]. | ||
+ | <!--T:67--> | ||
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. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_List_Filters_Header/<translate><!--T:122--> en</translate>}} | ||
+ | |||
+ | <translate> | ||
+ | <!--T:69--> | ||
+ | This section should only be included on help screens that describe Backend 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. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_List_Filters_Search_Tools/<translate><!--T:131--> en</translate>}} | ||
+ | |||
+ | <translate> | ||
+ | <!--T:134--> | ||
+ | Most of these help screens have search tools to filter by status, access and so on. Include a picture of the dropdown list boxes and describe each of them. [[<tvar name=1>S:MyLanguage/{{NAMESPACE}}:Components_Banners_Tracks</tvar>#Search_Tools|Here is an use example]]. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_Automatic_Pagination_Header/<translate><!--T:123--> en</translate>}} | ||
+ | |||
+ | <translate> | ||
+ | <!--T:135--> | ||
+ | This section should only be included on help screens that describe Backend screens; that is, where you have a list of items being shown. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_Toolbar_Header/<translate><!--T:124--> en</translate>}} | ||
+ | |||
+ | <translate> | ||
+ | <!--T:72--> | ||
+ | Obviously, this section should only be included on help screens where a toolbar is present. Describes the available buttons and their associated functions. It is best to provide a picture of the toolbar. | ||
+ | |||
+ | <!--T:145--> | ||
+ | '''Button Description''' | ||
+ | |||
+ | <!--T:74--> | ||
+ | The first word should always be a verb and, unless it is an irregular verb, it should also end in the letter ''s''. 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. | ||
+ | |||
+ | <!--T:75--> | ||
+ | For instance: | ||
+ | </translate> | ||
+ | |||
+ | <translate> | ||
+ | <!--T:76--> | ||
+ | * Instead of <tvar name=1>"To find buried treasures, click this button."</tvar> | ||
+ | </translate> | ||
+ | <translate> | ||
+ | <!--T:77--> | ||
+ | ** Say, <tvar name=1>''"Finds buried treasures."''</tvar> | ||
+ | </translate> | ||
+ | |||
+ | <translate> | ||
+ | <!--T:78--> | ||
+ | * Instead of <tvar name=1>"You can click this button to insert a picture of John Stamos into the current document."</tvar> | ||
+ | </translate> | ||
+ | <translate> | ||
+ | <!--T:79--> | ||
+ | ** Say, <tvar name=1>''"Inserts a picture of John Stamos."''</tvar> | ||
+ | </translate> | ||
+ | |||
+ | <translate> | ||
+ | <!--T:80--> | ||
+ | * Instead of <tvar name=1>"Inform yourself that a picture of John Stamos is the same thing as a buried treasure."</tvar> | ||
+ | </translate> | ||
+ | <translate> | ||
+ | <!--T:81--> | ||
+ | ** Say, <tvar name=1>''"Informs you that a picture of John Stamos is the same thing as buried treasure."''</tvar> | ||
+ | </translate> | ||
+ | |||
+ | <translate> | ||
+ | <!--T:146--> | ||
+ | '''Image File Naming Convention''' | ||
+ | |||
+ | <!--T:82--> | ||
+ | Since many toolbars are the same across multiple screens, the image file naming convention for toolbars is aimed at making it easy to re-use toolbar images wherever possible. | ||
+ | |||
+ | <!--T:83--> | ||
+ | Toolbar images should follow this naming convention: | ||
+ | </translate> | ||
+ | 'Help32-<iconslist>-toolbar-en.png'. <translate><!--T:147--> <tvar name=1><tt><iconslist></tt></tvar> is a <tvar name=2><tt>-</tt></tvar> separated list of the toolbar legends. Each word should be capitalised with spaces and <tvar name=3><tt>&</tt></tvar> removed.</translate> | ||
− | + | <translate> | |
− | + | <!--T:85--> | |
+ | Here is an example: | ||
+ | </translate> | ||
− | + | *<tt>Help32-Save-SaveClose-SaveNew-SaveAsCopy-Version-Close-toolbar-en.png</tt> | |
+ | {{Chunk30:Help_screen_Batch_Header/<translate><!--T:125--> en</translate>}} | ||
− | + | <translate> | |
− | This section should only be included on help screens | + | <!--T:87--> |
+ | This section should only be included on help screens that have a batch button. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_Quick_Tips_Header/<translate><!--T:126--> en</translate>}} | ||
− | + | <translate> | |
+ | <!--T:89--> | ||
As the name suggests, this section should include tips, hints, suggestions that can assist a user in performing tasks involving the screen. | As the name suggests, this section should include tips, hints, suggestions that can assist a user in performing tasks involving the screen. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screen_Related_Information_Header/<translate><!--T:127--> en</translate>}} | ||
+ | |||
+ | <translate> | ||
+ | <!--T:91--> | ||
+ | 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 good reason. | ||
+ | </translate> | ||
+ | {{Chunk30:Help_screens_Header/<translate><!--T:136--> en</translate>}} | ||
+ | |||
+ | <translate> | ||
+ | <!--T:137--> | ||
+ | A table showing related Help screens. | ||
+ | </translate> | ||
+ | <translate> | ||
+ | == Notes for Editors == <!--T:92--> | ||
+ | </translate> | ||
+ | |||
+ | <translate> | ||
+ | === Modify the Help Screen === <!--T:96--> | ||
+ | |||
+ | <!--T:97--> | ||
+ | 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 modify it: | ||
+ | |||
+ | <!--T:98--> | ||
+ | * Is the status at the moment <tvar name=1>'Ready'</tvar> or <tvar name=2>'To be moved'</tvar>? Change it to <tvar name=3>'Modified by [name]'</tvar> (replace [name] for your username at the Joomla Docs Wiki) | ||
+ | |||
+ | <!--T:99--> | ||
+ | * Is the status at the moment <tvar name=1>'To be reviewed'</tvar>? You don't have to change the status in that case. | ||
+ | </translate> | ||
+ | |||
+ | <translate> | ||
+ | ===Image Naming Guidelines=== <!--T:100--> | ||
+ | </translate> | ||
+ | |||
+ | <tt><nowiki>Help30-[menu-system-path-separated_by_dashes]-[screenElementType]-en.png</nowiki></tt> | ||
+ | <translate> | ||
+ | <!--T:101--> | ||
+ | * Replace <tvar name=1><tt>[menu-system-path-separated_by_dashes]</tt></tvar> with the names of the menu items that you would need to select to get to the item you are taking a screenshot of.</translate>{{-}}<translate><!--T:138--> Separate menu items with a hyphen <tvar name=1><tt>-</tt></tvar> and if the menu item name has more than one word in it, separate the words with an underscore <tvar name=2><tt>_</tt></tvar>.</translate>{{-}}<translate><!--T:139--> | ||
+ | Do not use spaces in your file name. Replace spaces with the underscore <tvar name=1><tt>_</tt></tvar> character. | ||
+ | </translate> | ||
+ | <translate> | ||
+ | <!--T:102--> | ||
+ | * Replace <tvar name=1><tt>[screenElementType]</tt></tvar> with the type of the screen element that your picture contains.</translate>{{-}}<translate><!--T:140--> Screen element types are:</translate> | ||
+ | ** ''screen:'' <translate><!--T:103--> This is a screenshot of the entire menu item.</translate> | ||
+ | ** ''toolbar:'' <translate><!--T:104--> This is a picture of the menu item's toolbar.</translate> | ||
+ | ** ''menu:'' <translate><!--T:105--> This is a picture of the menu item's menu bar.</translate> | ||
+ | <translate><!--T:106--> *: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.</translate> | ||
− | + | <translate> | |
− | + | <!--T:107--> | |
+ | '''Examples Using the Guidelines:''' | ||
+ | </translate> | ||
+ | <translate> | ||
+ | <!--T:108--> | ||
+ | * A screenshot of the Extension Manager's "Discover" screen would be named: | ||
+ | </translate> | ||
+ | *:<tt>Help30-extensions-manage-discover-screen-en.png</tt> | ||
+ | <translate> | ||
+ | <!--T:109--> | ||
+ | * A screenshot of the Extension Manager's "Discover" screen toolbar would be named: | ||
+ | </translate> | ||
+ | *:<tt>Help30-extensions-manage-discover-toolbar-en.png</tt> | ||
− | + | <noinclude> | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | <noinclude> | ||
[[Category:Style guides|{{PAGENAME}}]] | [[Category:Style guides|{{PAGENAME}}]] | ||
− | |||
</noinclude> | </noinclude> | ||
− | <noinclude>{{cathelp|3.0,3.1}}</noinclude> | + | <noinclude>{{cathelp|3.0,3.1,3.2,3.3,3.4,3.5,3.6,3.7,3.8,3.9,3.10}}</noinclude> |
Latest revision as of 16:09, 15 October 2022
Return to Joomla 3.10 Help Screen Wiki Page
This should be used as a guideline for creating Help screens. 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.
If you have a question, please post in on the associated talk page of the help screen by clicking Actions → Discussion buttons.
Description
Every help screen should begin with a Description section. This goes into detail about what the screen does. 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 specific details.
Keep the description short and to the point. If the description is long, consider using bullet points to summarise it.
How to Access
Every help screen should have a How to Access section listing 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 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 is an example:
- Select Content → Articles from the dropdown menu of the Administrator Panel
Example's chunks and parameters:
- {{Chunk30:Help_screen_How_To_Access_By_Menu/<translate>en</translate>|<translate>Content,Articles</translate>}}Learn more about using chunks in Joomla help screens.
Note:
- You "click" on buttons, including toolbar buttons, but you "select" menu items. Consistent use of this terminology should help users.
Screenshot
Screenshot showing the overall look of the screen.
Please always use screenshots with |800px in the code whenever they are large. This way any size can be added and it will help translators to be able to add transcreated images without having to notice the width.
Notes:
- The filename should follow our Image naming guidelines for help screens.
- The filename should always include a language code at the end of the name. For English, -en is added.
- You can use either .png or .jpg files.
Column Headers
This section should only be included on help screens that describe Backend screens; that is, where you have a list of items being shown. This section should describe each of the list columns.
Column Filters
This section describes the dropdown input fields above the column headers.
Details
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 such as Site Global Configuration and Article Options.
If fields are grouped into fieldsets or tabs then group the fields under sub-headings.
List Filters
This section should only be included on help screens that describe Backend 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.
Search Tools
Most of these help screens have search tools to filter by status, access and so on. Include a picture of the dropdown list boxes and describe each of them. Here is an use example.
Automatic Pagination
This section should only be included on help screens that describe Backend screens; that is, where you have a list of items being shown.
Toolbar
Obviously, this section should only be included on help screens where a toolbar is present. Describes the available buttons and their associated functions. It is best to provide a picture of the toolbar.
Button Description
The first word should always be a verb and, unless it is an irregular verb, it should also end in the letter s. 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."
Image File Naming Convention
Since many toolbars are the same across multiple screens, the image file naming convention for toolbars is aimed at making it easy to re-use toolbar images wherever possible.
Toolbar images should follow this naming convention: 'Help32-<iconslist>-toolbar-en.png'. <iconslist> is a - separated list of the toolbar legends. Each word should be capitalised with spaces and & removed.
Here is an example:
- Help32-Save-SaveClose-SaveNew-SaveAsCopy-Version-Close-toolbar-en.png
Batch Process
This section should only be included on help screens that have a batch button.
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 good reason.
Help Screens
A table showing related Help screens.
Notes for Editors
Modify the Help Screen
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 modify 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 Naming Guidelines
Help30-[menu-system-path-separated_by_dashes]-[screenElementType]-en.png
- 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 hyphen - and if the menu item name has more than one word in it, 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 toolbar.
- 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 Guidelines:
- A screenshot of the Extension Manager's "Discover" screen would be named:
- Help30-extensions-manage-discover-screen-en.png
- A screenshot of the Extension Manager's "Discover" screen toolbar would be named:
- Help30-extensions-manage-discover-toolbar-en.png