This is a work in progress and should be used as a guideline for creating help screens for Joomla 3.x. This offers consistency throughout the help screens to allow for easier navigation. Feel free to add to this.
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:
|To access this screen:
If there is more than one way to access the screen, list them all. For example:
To access this screen you can either:
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.
Screenshot showing the overall look of the screen.
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:
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
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.
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.
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.
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 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.
This section should only be included on help screens where the screen has a batch process feature. For example, see Help30:Components Banners Categories.
As the name suggests, this section should include tips, hints, suggestions that can assist a user in performing tasks involving the screen.
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.