visual style guide

Visual Style Guide

Version 1.5.2 Joomla! User Documentation Team

Andy Wallace 20th June 2007

20th June 2007 Andy Wallace

Visual Style Guide

Change Log Change Date By

whom + Table illustration 1.5.1 + Updated tables 1.5.0 12 June 2007 AW + Quick Reference 12 June 2007 AW - Crib Sheet -“- AW * Format 11 June 2007 AW + Change log -“- -“- + License & Acknowledgements -“- -“-

20 June 2007 Joomla! User Documentation Team

Visual Style Guide

License & Acknowledgements License This document is released under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license.

Acknowledgements I would like to pass on my thanks to the following members of the User Documentation Team for their efforts of proof reading and ideas on this document: Chad McKissick Leandro Bergantiños – for the Quick Reference Brian Lieske Thanks Andy Wallace


http://creativecommons.org/licenses/by-nc-sa/3.0/

http://creativecommons.org/licenses/by-nc-sa/3.0/

Visual Style Guide

Table of Contents Change Log ....................................................................................................................................................2 License & Acknowledgements.......................................................................................................................3

License..................................................................................................................................................3 Acknowledgements ..............................................................................................................................3

Introduction....................................................................................................................................................6 CSS & XHTML – a Quick Summary ............................................................................................................7

Elements ...............................................................................................................................................7 Replaced and Nonreplaced Elements ...................................................................................................7

Replaced elements ............................................................................................................................7 Nonreplaced Elements......................................................................................................................7

Block-level and Inline-level Elements..................................................................................................7 Block-level elements ........................................................................................................................7 Inline-level elements.........................................................................................................................7

Headings.........................................................................................................................................................8 Headings - Help Screen Style ...............................................................................................................8

Page Title..........................................................................................................................................8 Section Titles ....................................................................................................................................8 Sub-section Titles .............................................................................................................................8

Lists................................................................................................................................................................9 Vertical Lists ........................................................................................................................................9

Ordered Lists (ol)............................................................................................................................9 Unordered Lists (ul)........................................................................................................................9

Horizontal (In-sentence) Lists ..............................................................................................................9 Lists - Help Screen Style ......................................................................................................................9

Example:.........................................................................................................................................10 Notices .........................................................................................................................................................11

Notices - Help Screen Style................................................................................................................11 Tables...........................................................................................................................................................13

Tables - Help Screen Style .................................................................................................................13 Table Layout...................................................................................................................................13 Table Header (thead) ......................................................................................................................13 Table Heading (th)..........................................................................................................................13 Table Data (td)................................................................................................................................13 Table First Column.........................................................................................................................13 Images in tables ..............................................................................................................................13

Highlighting .................................................................................................................................................14 Highlighting - Help Screen Style........................................................................................................14

Glossary & Definition Styles .......................................................................................................................16 Creating a new definition list from scratch.........................................................................................16 Creating a new definition list from an existing list of entries.............................................................16 Definition Lists – Help Screen Style ..................................................................................................16

Fonts & Colour (color).................................................................................................................................17 URL’s and Links..........................................................................................................................................18

URL’s .................................................................................................................................................18 Example URL’s ..................................................................................................................................18 Directory Paths ...................................................................................................................................18 Internal Links......................................................................................................................................18

Anchors ..........................................................................................................................................18 Links to other Help Screens............................................................................................................19

Images ..........................................................................................................................................................20 Graphics — an overview ....................................................................................................................20

Objects............................................................................................................................................20 Numbers .........................................................................................................................................20 Concepts .........................................................................................................................................20 Words .............................................................................................................................................20

Formatting Requirements ...................................................................................................................20 Labels .............................................................................................................................................20


Visual Style Guide

Keys................................................................................................................................................20 Titles ...............................................................................................................................................20 Cross-referencing ...........................................................................................................................21 Size of illustrations .........................................................................................................................21

General guidelines for graphics — a review ......................................................................................21 Images – Help Screen Style................................................................................................................21

Screenshots .....................................................................................................................................21 Thumbnails .....................................................................................................................................21 Icons ...............................................................................................................................................21 Inline icons .....................................................................................................................................22

Help Screen Template Example...................................................................................................................23 General ...............................................................................................................................................23 Fixed Elements ...................................................................................................................................23 As Required Elements ........................................................................................................................23 Header Block......................................................................................................................................23

Editable regions ..............................................................................................................................23 Example of Help Screen Template .................................................................................................24

Further Reading............................................................................................................................................25 Feedback.............................................................................................................................................25

Quick Reference Guide


Visual Style Guide

Introduction Visual Style can mean different things to different people, but here it will mean the use of typographical and formatting elements as they affect the presentation of documentation on the Help Site and to a lesser degree, upon the Workshop site, as well as how we use these elements in the production of hard-copied material. Our focus here is all aspects of “user” documentation within the Joomla! Help Site remit and the production of a formal guide for this in the hope that we attain conformity from all parties that provide material on this resource. Control of most of the formatting and typographical elements that we reference in this guide is directly within the template_css.css of the Help Site and Workshop Site themselves it is more a case of making people aware of what is available and when and how it should be applied within a document.


http://help.joomla.org/

http://help.joomla.org/workshop/

Visual Style Guide

CSS & XHTML – a Quick Summary In formatting a page, it is useful to understand a few basic HTML principles:

Elements Elements are the means of managing the appearance of a web page with Cascading Style Sheets (CSS). CSS styles use HTML markup elements as the basis for style application in a document. Common elements are p, table, span, h1, div, and a. There are two types of Element in use and that we are interested in:

Replaced and Nonreplaced Elements Replaced elements Replaced elements are those where the elements content is replaced with something not represented by the current documents content. The following code snippet shows a typical example of this:

<img src=”whatever.png” />

You do not see the words within the snippet, what you do see the image named whatever.png.

Nonreplaced Elements Nonreplaced elements appear in the following form:

<element_name & details>the displayed content</element_name>.

You do see the displayed content whilst the surrounding code applies the relevant CSS settings.

Block-level and Inline-level Elements Block-level elements Block-level elements create a container around their content, which prevents other elements of any form existing at its sides. Common examples of this in HTML are the p and div elements. They in fact force a break to appear before and after their content

Inline-level elements Inline-level elements also create a container around their content; however, the major difference is they act upon content, within another element such as a block-level element. Example of block and inline elements:

Heading – h1 (block) A paragraph generally follows a heading. This paragraph (p) is a block-level element. If we were to emphasize (italic and bold) any text it would be an inline element within the block-level paragraph. The content either side of the inline elements actually remain a part of the block element and unaffected by the inline element.

Visual Style Guide

Headings The following presents some of the standard guidelines on headings. With online information, you want to use many headings, perhaps one heading for every two to three paragraphs. Headings are block-level elements. Of course, headings can be overdone:

• Too many headings with only one or two sentences per heading do not work. • Heading format is set within the CSS of the site and should not be altered other than

by applying individual styles such as within the Help Screens. • Make headings descriptive of the sections they introduce. • Avoid "stacked headings" — that is two or more consecutive headings without

intervening text. • Avoid referring to headings with pronouns in the text following headings. If you have a

heading like "Configuring Joomla!", do not follow it with a sentence like "This next phase..."

Headings - Help Screen Style All headings have the Style hs15 applied to them.

Page Title Format the page title as heading 1 (h1).

Section Titles Format the main section titles as heading 2 (h2)

Sub-section Titles Add further headings for sub-sections as required – heading 3 (h3) and heading 4 (h4). In most situations, it should not be necessary to have more than four levels of heading, particularly with the effective use of definition term and definition description and list styles. If this is not the case, consider revising the overall layout of the content and create a further higher-level section or sub-section.


Visual Style Guide

Lists Lists are useful tools for emphasizing important points, enabling rapid scanning of text, and provide more permitted white space. The following are the requirements for the use of lists. Use the standard numbered- and bulleted-list format selected from the JCE Editor. Use vertical lists as opposed to in-sentence lists when you want the emphasis provided by the vertical presentation. In-sentence lists provide only minimal emphasis; vertical lists provide much more. Avoid using in-sentence lists when there are more than four or five items; use a vertical format instead.

Vertical Lists Ordered Lists (ol) Only use Ordered lists for items that are in a required order, for example a sequential installation process or, that requires specific reference to, by number, from within the main body of a page. See the example below for enclosed lists.

Unordered Lists (ul) If no particular order is required, use a bulleted list to display the items - a list of Joomla! Extensions for example.

Horizontal (In-sentence) Lists When using in-sentence lists, use numbers (1), (2), and so on for the main level. If you need a sub list use letters (a), (b), and so on, to contrast with the numbers. Where a third level is required, use Roman numerals (i), (ii), and so on. It is only possible to create in-line lists manually. Always surround inline list-item numbers by brackets. Do not use without brackets or just a single, closing bracket.

Lists - Help Screen Style • Introduce all lists with a lead-in; do not use headings as lead-ins to lists. • To create a new paragraph within a list item, press Ctrl+Enter this will add a line break

 to the HTML code. • Do not add additional line breaks between list items. • Terminate list items with a full stop (period), only when they are complete sentences or

they have embedded dependent clauses in them. • Use initial capitals on the first word of all list items. • Do not create lists with an excessive number of items. Consider seven to ten items as

the maximum for lists. • On a standard page, ensure there are no more than two or three lists, and that at least

three or four lines of regular text occur between them. • For nested lists the second-level list items are created by a single click of the Tab key

which will make sure that nested items align to the text of the previous level.; use lowercase letters for second-level numbered list items, and lowercase roman numerals for the third.

• See the example on the next page.

Visual Style Guide

Example: The numerals used by the JCE Editor are the same for all levels; to alter this edit the ol element by adding the following code:

<ol> <li>list</li> <li>list <ol style="list-style:lower-alpha"> <li>list <ol style="list-style:lower-roman"> <li>list</li> <li>list</li> </ol> </li> <li>list</li> </ol> </li> <li>list</li> <li>list</li> <li>list</li> </ol>

This results in the following display:

1. list 2. list

a. list i. list ii. list

b. list 3. list 4. list 5. list

Visual Style Guide

Notices Notices are specially formatted chunks of text that will alert readers to potential problems, danger, code details, further information, and general information.

Notices - Help Screen Style Four specific notice styles have been created for the online documentation within the Workshop and Help Site. Access each via the Style drop down box of the JCE Editor:

Apply a notice Style to a paragraph block of text within the document as follows:

1. Type the text of the notice itself. 2. Place the cursor at the beginning or end of the block of text that is to form the

notice. 3. Apply the format paragraph to the whole block of text by selecting it from the

Format drop down list. 4. Ensure the cursor remains at the beginning or end of the now configured paragraph

block of text and select the hsnote (or hscode, hsinfo, hswarn, or hscaution) style from the Style drop down list.

5. Apply any essential formatting to inline elements needed. This formatting might relate to code elements or URL references for example.

You must follow this process precisely otherwise, the likelihood is that the Style is not applied. In the event that this happen open the HTML editor panel, and delete the incorrect code from the item. The code in the HTML editor should look like the following (in the case of the Note style of notice): then your text If the layout of the text appears as follows… then your text …or then your text …delete the references … and click the Update button and follow the process listed above again. Alternatively, you can add the correct code manually whilst the HTML editor screen is open. Do not alter any formatting to the notice style.

• If possible, insert Warning and Caution notices at the beginning of the entire procedure to which they apply.

• An action that cannot be undone must include a Warning notice.

Visual Style Guide

• Only apply additional inline-level formatting to text within a notice when needed to indicate code, a URL or anchor reference, or other specific requirement of this style guide.

• Do not add extra line breaks before or after the notice • On Warning or Caution notices, in addition to telling readers to do or not to do

something, explain what will happen if they ignore the warning, under what conditions the situation might occur, and how they recover the situation if the statement is ignored.

• Make the text of notices succinct, but not at the expense of clear writing. Avoid an over concise writing style in notices. You are not sending an SMS message to the reader after all! ☺

• In numbered lists, align notices to the text of the list item to which they apply. • To create a further “paragraph” within a notice press Cntrl+Enter keys together to

insert a line break . If more than two paragraphs are required, consider using a standard text block with its own heading, to go into detail and restrict to a shorter summary or altogether omit the content of the notice.

Visual Style Guide

Tables Tables are essentially vertical lists. However, they are more structured and formal. In your text, look for repeating groups of items that it would be appropriate to format as tables. For example, a series of terms and definitions is a classic use for tables. The following are some of the standard guidelines for tables.

• Make the table title the top row of the table. • Use a table title even when the content of the table is utterly obvious, to ensure the

accessibility to the content for the visually impaired that may be using a screen reader. • Use column and row headings (or both) to define the contents of the columns and

rows. • Put standard measurement units in the column or row heading rather than with each

item in the column or row.

Tables - Help Screen Style Create tables using the standard facilities available within the JCE Editor. When formatting a table it is necessary to add the individual styles from the Styles drop down list, or using the class id list within the table editor. Do not alter the preset style or formats other than by the use of Format and Style lists within JCE and the CSS template. Do not alter the position of text within any tables that you create; the formatting styles will control this.

Table Layout External borders are 5px blue ridged. Internal borders are 1px blue solid. Table widths - always try to set this to a percentage in order that it sets its size according to the Users screen resolution.

Table Header (thead) All tables should have, whenever possible, a title added. This is to assist with those people using screen readers amongst other things. Add the style th15.

Table Heading (th) Apply the table header element th to the top row of the table for the column headings, and add the style th15.

Table Data (td) For all other standard content use the td element and add the style td15.

Table First Column If the left hand column also contains items that require highlighting (row headings) use the standard table data element td to the content, and then add the style tc15.

Images in tables In tables that display an image, or a column of images, for example a list of toolbar icons, set the image to display in the centre of the column.


Visual Style Guide

Highlighting Software documentation typically uses a lot of highlighting within the main body of text. Highlighting here refers to bold, italics, alternate fonts, caps, quotation marks, and other such typographical elements used to call attention to text.

These styles are not what we apply to the actual definition terms, titles, or headings in their primary context just when referring to them within the main content.

Highlighting - Help Screen Style Commands

Use the hscom style for any command or subroutine, unless it is in an example. For example, "Use the rename command to change the name of the file."

Menu and command buttons Use the hscom style to highlight buttons on graphical user interfaces. For example, "Press Exit to exit the program." Or, "Press Format for a list of choices."

Variables, placeholders Use the hsvar style for placeholder names where readers must enter their own values. For example, "To change directories, use the cd NewDirectoryName command." Readers will replace NewDirectoryName with the name of an actual directory on their own computer. Or, copy oldfile newfile. Users will generally know not to type oldfile or newfile but to substitute his, or her, own file names instead.

Text that the User must enter Use the hsmust style, for text that readers must type in verbatim. For example, "To install the program, type: setup Joomla! and then press Enter."

Text displayed on the screen Use the hsscreen style for text that the computer displays, such as error messages. For example, if the directory does not exist, the system will respond with – “No such file or directory."

Examples Use the hsincode style, for inline-level code examples. The most common usage here is for file names or single PHP commands. For example, {mos_pagebreak} Or, screen.menus.html

Extended Code Examples Use the Notice style hscode to highlight extended code examples when they are more than a few words in length (certainly any more than one line in length).

Menu Names Use the standard type style for body text, without emphasis for menu or screen names, but copy the cap style actually used in the menu or screen. For example, "In the Format dialogue box, you have a number of choices." Link the first occurrence of a Menu/Function Name in a page to the Help Screen explaining that particular screen.

Field names (labels) Use the standard type style for body text for field names (the text labels beside boxes in which you enter data or make choices), but copy the cap style used on the screen. For example, "In the Title Field, enter the name for this Article."

Keyboard keys and mouse buttons Use the hsinput style for names of keys on the keyboard, and copy the exact spelling and cap style. For example, "Press the Home key to move the text cursor to the beginning of the line." Or, “Press the Ctrl+Enter keys to insert a line break.” For mouse buttons, use lower case, for example, "Press the left mouse button."


Visual Style Guide

Extended emphasis If any text more than two or three words must be emphasized (other than menu access paths), use Notices (see Notices Section) instead of making the extended text all-bold, all italics, all caps, or some other combination.

Underscore Never use underscores to emphasise a word.

Capitalisation Never use all-caps to highlight a word. Capitalisation is an important issue with particular regard to proper names used within Joomla!

• Use the exact capitalization style of messages shown on the computer screen, menu or screen names, field names, hardware labels, and so on.

• Do not use capital letters for emphasis; use italics or bold instead following the guidelines above.

• Do not use all-caps for any text. The only exception to this is within code extracts where it is a direct representation of the code.

All the key components, menus, functions, and more must be capitalised. For example, Modules, Plugins, Components, Section Manager, Site Menu, Menu Item, Article…

Single and double quotation marks. All too often writers use quotation marks incorrectly to emphasise text. Limit the use of quotation marks to identify quoted speech; numbers, letters, or words referred to as such. One of the primary reasons (other than it is wrong!) is that some readers might mistakenly assume that they must include the quotation marks in the commands they enter.

Single and Double Quotation Examples

Incorrect Correct

Use the "move" command. Use the move command.

Enter "copy install installnow." Enter copy install installnow.

Do not use single quote marks at all.


Visual Style Guide

Glossary & Definition Styles In the past creating Glossary and Definition listings was a manual process of formatting and styling each term and description in isolation. This provides no option to change the style or format of a whole list in one easy step and every field has to be individually changed. To change this, standard HTML classes – definition list (dl), definition term (dt), and definition description (dd), have been added to the Format list in the JCE Editor.

There is an outline template for a Glossary Style Index in the Workshop site.

Creating a new definition list from scratch 1. Enter the first term of the new definition list or glossary 2. Select the definition term element from the Format drop down list 3. Press the Enter key, and the cursor will drop to the next line and appear indented 4. Enter the description of the term, the definition description element is added

automatically, 5. Press the Enter key again, the cursor will drop to the next line but will revert to the

position for the next definition term. 6. Enter the next term…and repeat steps 3, 4, and 5 until the list is complete. 7. When you reach the end of the list and want to carry on with other text entry, press

the Enter key twice, and the list is complete and you will have exited from it.

The JCE Editor adds the definition list element to the list automatically when you add the first definition term element.

Creating a new definition list from an existing list of entries 1. To create a definition or glossary list of items from an existing list of items each with

a simple press of the Enter key to insert a line break (yes I know that I have previously said do not add these but bear with me!).

2. When the list is complete, highlight the whole list (terms and definitions together) and select definition term from the Format list. The JCE Editor will add the definition list element automatically in the same way as it adds an ol or ul tag in a list situation.

3. Finally, select each of the definition descriptions in turn and, with the cursor at one end of the line select the definition description element from the Format drop down list.

Definition Lists – Help Screen Style For all definition and glossary lists that are within the Help Screens, ensure that you use the following styles in addition to the base elements dt and dd.

• For definition terms (dt) use the Style dt15. • For definition descriptions (dd) use the Style dd15 • Definition lists do not need the application of a separate style.

To add these styles simply place the cursor at the end of each term and description and select the style for the drop down list.


Visual Style Guide

Fonts & Colour (color)

The Help Site and Workshop Site CSS templates determine fonts and font colour.

Do not alter either of these without clearing this with the UDT Leader first.


Visual Style Guide

URL’s and Links URL’s Create Web links to external web sites using the link system within JCE. Ensure you enter a title as well as completing the full URL itself, for example http://help.joomla.org. See below for two examples of the correct code that you must complete for every link. The first uses the text of the item as the link that the user will see; the second uses the actual URL itself. Either is acceptable but should be appropriate to the situation under consideration.

<a href="http://help.joomla.org" title="This is the text that appears when you mouseover the URL. Do not just state "link" or something equally non-helpful, this is supposed to be an accessibility aid." target="_parent">This is the text that is displayed on the site it may be the full URL itself or a word (s) that indicate the target site.</a>

This is the text that is displayed on the site. It may be the full URL itself or a word (s) that indicate the target site.

<a href="http://help.joomla.org" title="The Official Joomla! Help Site" target="_parent">http://help.joomla.org</a>

http://help.joomla.org

Example URL’s It is often necessary to include examples of a URL that a User must enter, for example http://www.mydomain.com clearly these are not active links and we do not therefore want to have them behaving as such. Accordingly, when displaying an example URL highlight these by using the Courier font type only. If the JCE Editor tries to create these as active URL’s simply, break the link by clicking the broken chain link icon. Where there is text that a User must replace with his, or her, own details emphasise these with italics as well. Always use http://mydomain.com as the example for the Users own web site.

Directory Paths A path to a file in a directory is generally displayed as /directory name/file name, to distinguish the fact that we are talking about a directory within the Joomla! core root directory always state this as joomla_root/directory name/file name. This shows we mean where the User may actually have installed the active root of Joomla! and not for example, the server root directory.

Internal Links Anchors To create an anchor to a particular word or phrase (or a position adjacent to it within the current working document,

1. Position the cursor to the position the anchor is to appear, or highlight the text if the whole word is to be used

2. Click the Anchor icon in the JCE Editor 3. Enter a name for the Anchor in lower case and without any spaces 4. Confirm the item. 5.

To then add a link to the anchor from another part of the page, 6. Select the word that is to become the active link 7. Click upon the link icon in the JCE Editor 8. Select the drop down list of Anchors and select the name that you gave to the anchor

from the list 9. Complete the Title and Target fields as required 10. Click the Insert button






http://www.mydomain.com/

Visual Style Guide

Links to other Help Screens It is a necessary part of the Help Screen writing process, as with many other document classes in Joomla!, to cross-reference, and link, to other Help Screens. In order to ensure that these links work and are transferable when transferring the pages to another site whether it is the Help Site, or in a dump file for the Translation Partners, we must create these links in a very specific manner. The method to link to another Help Screen is by using the variable key reference assigned to each of the screens within the Help Site and the local files.

“index.php?option=com_content&task=findkey&pop=1&keyref=screen.screenname.15”

Never change the key reference within a Help Screen unless instructed to do so to correct an error.

When migrating these Help Screens to standalone HTML documents as the local Help files within the Joomla! core you must edit this reference down to… Under Joomla! 1.5 the code has altered and whilst we do not need to worry about this just yet, it is worth including for future reference. The code will be as follows:

“index.php?option=com_content&task=findkey&tmpl=component;1&keyref=screen.screenname.15”


Visual Style Guide

Images You might think, producing graphics is a difficult prospect — in fact, can be fun and a break from all that writing. You do not have to be a graphics artist to produce graphics for your technical writing. Most of today’s graphic software permits you to produce effective and consistent graphics with relative ease. If you do not feel confident creating the images yourself, add highlighted text that an image is required, where the original can be found, and pass it along to another team member.

Graphics — an overview Before getting into details on creating, formatting, and incorporating graphics, we will look at the types of graphics and their functions. You can use graphics to represent the following elements in your technical writing:

Objects If you are describing a Joomla! function Manager, you will probably need a screenshot of the thing. If you are explaining how a Module works, you will need some illustrations of the configuration of how that Module in the Back-end and the resulting display in the Front-end. Photographs, drawings, diagrams, and schematics are the types of graphics that show objects. Screenshots, icons, and mini-icons are all objects.

Numbers If you are discussing the number of downloads of Joomla! over a period, you could use a table with the columns being for each month since 2005; the rows could be for different version numbers. You could show the same data in the form of bar charts, pie charts, or line graphs. Tables, bar charts, pie charts, and line graphs are some of the principal ways to show numerical data.

Concepts If you wanted to show how Joomla! is organised, the relationships of the different Work Groups, and the core team, you could set up an organisation chart - boxes and circles connected with lines that show how everything is hierarchically arranged and related. This would be an example of a graphic for a concept: this type depicts non-physical, conceptual things, and their relationships.

Words We can use graphics to display words in order to emphasise them more. It is good idea to keep in mind as a useful technique in certain situations.

Formatting Requirements When you use an illustration in a Help Screen or manual, there are several requirements to keep in mind.

Labels Identify the parts of an illustration you are including with labels when this is not clear from the image itself. Generally, we do not be need these on a Help Screen. Where you add labels to a graphic ensure all the titles or alternative text in the code is complete to ensure compliance with accessibility rules.

Keys If the illustration, for example a flow chart, has certain shadings, colours, line styles, or other such details that have a particular meaning, explain these in a key.

Titles Except in certain cases where the graphic is clearly associated with the subject matter – as in a Help Screen screenshot, illustrations must have titles. These titles should be numbered (Figure 1, Figure 2, and so on). Other exceptions to this rule are if for example,


Visual Style Guide

• In certain documents, there are illustrations practically after every paragraph and if there is no benefit from placing the titles

• If you only have one or two illustrations and they are not cross-referenced; • In certain cases, you might want to keep the title but discard the word Figure and the

number following it.

Cross-referencing Refer to illustrations from the relevant point in the document. Use a brief description to the illustration.

Size of illustrations Essentially, we will use two types of illustration the inline graphic and the pop-up graphic linked to an inline thumbnail or text link. Scale inline graphics appropriately to meet their intended purpose and to fit within the designated page area.

General guidelines for graphics — a review • Use graphics wherever and whenever their use will add value to the topic under

discussion. Do not shy away from using graphics because it appears like too much hard work. If you are genuinely unable to do the graphics – someone else on the team will be able to assist.

• Ensure a graphic is adjacent to the text that explains its contents. If it is too large for the immediate space available, add it to the top of the next page instead.

• Do not just use graphics as content filler - this serves no purpose. • The graphics that we use always need to be relevant to the subject matter and the

target audience. • Use figure titles for graphics (there are exceptions to this rule –see above – but only a

few them). • Ensure the use of cross-referencing where this is appropriate and necessary. • Include identifying detail such as illustration labels, axis labels, keys, and so on, where

these will add to the value of the graphic and therefore add to the content itself. • Make sure graphics fit within normal margins.

Images – Help Screen Style All images created for the Help Screens and in fact all Joomla! User Documentation, are to be created in the PNG8 format with compression. This ensures the best clarity for the smallest file size possible.

Screenshots We present Screenshot graphics using two images. The first is a thumbnail, with an active link that causes a popup window to appear when clicked displaying the second image that displays at the full resolution at which it was made up to a maximum width of 1000px with an automatic height setting. Images for the screenshots are contained in the /images/stories/1.5 help screen/… directory.

Thumbnails Thumbnails should be set with a width of 150px. The height should be set to 100px These are always the settings for this object.

Icons Display images, such as the toolbar icons at the same resolution as the original and using the same format wherever possible. Generally, this will be 32x32 pixels (px).


Visual Style Guide

Inline icons It is essential that you insert these so that they do not disrupt the text around them. This will depend on the padding setting within the Image Manager, the actual size of the image, and any unnecessary “white space” that may occur as a result of a difference between the Image and Canvas sizes of the original image.


Visual Style Guide


Help Screen Template Example General

Do not change the order and layout of the template other than the removal or renaming of As required elements see below. Do not modify Fixed elements.

Do not alter any of the formatting, colors, or spacing within the Header block of the Help Screens. The CSS template controls all these. This will ensure a consistency of appearance from one screen to the next.

Some of these appear slightly differently to the standards explain within this document by design.

Fixed Elements Do not alter these items or the order in which they appear.

• The Header Block • Description • Version Changes

or • Typical Usage • Quick Tips • Issues • Dependencies

As Required Elements • Remove these items when they are not required. • Rename the Other Sections to match a particular requirement. • Unique Column Headers • Unique Details • Unique Filters • Editor Screens • Other Sections 1-3

Header Block

Do not edit the table configuration in any way.

Editable regions • Edit the Contents list to reflect the actual Section Headings present in the current

screen. Ensure that you modify the link Title to represent the name and description of the Section.

• Edit the Parent Function, Type, Task, Access, and Further Information fields of the block to reflect the content of the actual screen under review.

• Delete the two unnecessary icons under the Min. Access Level field leaving the icon that correctly represents the minimum assigned Access Level a User requires to access the function of the screen under review.

• Replace the Image Placeholder image with the correct image for the screen under review.

• See the example on next page…

Visual Style Guide


Example of Help Screen Template

Visual Style Guide


Further Reading Visual Style, whilst an essential way of conveying the information we want to the User, is only a part of the story. You must always create Joomla! User Documentation in accordance with this reference together with:

• The Editorial Style Guide • The Documentation Process Guide • The Oxford English Dictionary • We will announce other variations, from time to time, in the Joomla! User

Documentation forums – which should be visited on a regular basis whilst involved in the Project

Feedback If you have any feedback or suggestions please either post on the User Documentation Forum or contact the UDT Team Leader by PM or e-mail.

Visual Style Guide – Quick Reference – V1.1.1

Name Element Style Use 1. Headings Heading 1 h1 hs15 Help Screen Title Heading 2 h2 hs15 HS Section Heading Heading 3 h3 hs15 HS Sub-section Heading 4 h4 hs15 HS Sub-section 2 2. Lists Ordered lists ol Sequential process, Numbered references (more emphasis) 7-10 items - sub-list 1 ol a,b,c, style="list-style:lower-alpha" --sub-list 2 ol i, ii, iii, style="list-style:lower-roman” Unordered lists ul Items relate (Always use JCE format: bullet list) 7-10 items

In-sentence lists - Horizontal List up to 4-5 items: Use (1), (2)… and (a), (b)…less emphasis

3. Glossaries & Definitions Definition list dl dl15 This element is added automatically (don’t use style) Definition term dt dt15 Enter first term, select format and press enter Definition description dd dd15 Enter definition and press enter (double enter to finish) 4. Notice Styles Cautionary p,td,dd,li, hscaution Use to describe potential problems that may occur. Code p,td,dd,li, hscode PHP, JavaScript, MySQL, HTML, CSS Further information p,td,dd,li, hsinfo Related information to consult Note p,td,dd,li, hsnote Definition of additional points Warning p,td,dd,li, hswarn Use to describe problems that will occur. 5. Tables

Layout - Outside border 5px ridged blue, internal borders 1px, blue, solid, width by % whenever possible.

Title thead th15 Always add a table title and alt description Heading th th15 Use for table column headings First column td tc15 Use to highlight first column row headings (terms) Data td td15 Use with all standard content Images td With image lists, set image to display in the centre of the column 6. Highlighting Commands p,td,dd,li, hscom Subroutines, Menus, Commands, Buttons Variables p,td,dd,li, hsvar Placeholder names (text to replace) Text input p,td,dd,li, hsmust Text typed by the user, Example URLs Text output p,td,dd,li, hsscreen Text displayed by the system Code inline p,td,dd,li, hsincode Examples of small amount of code Keyboard/Mouse p,td,dd,li, hsinput Keyboard keys, Mouse buttons 7. Emphasising

Capitalisation p,td,dd,li, Menu-Field-Screen Names, Screen Messages, Key Components… Only in text

Underscore Never use underscore to emphasise a word Quotation marks Only for quoted speech, Numbers, Letters, Words referred to as such 8. Fonts & Colour Do not alter fonts and font colour determined by templates Do not include additional line breaks, empty paragraphs, or other forms of whitespace 9. URLs, Directory Paths, Internal and External Links External Link Enter the full URL (http://help.joomla.org) and a title for the URL

Example or Directory Path Use hsmust (required part) and hsvar (domain part). Commonly:(http://mydomain.com) or (joomla_root/directory_name/file_name)

Internal Links Enter an anchor in the target position and then a link in the origin Link to another HS “index.php?option=com_content&task=findkey&pop=1&keyref=screen.screenname.15”10. Images General Use PNG8 format with compression Thumbnails Set all to: Width 150px, Height 100px Screenshots Up to a maximum width of 1000px (use a thumbnail link) height auto Icons Use original files if possible (usually: 32x32px or 16x16px)

Inline Icons Use original files. Try not to disrupt the text around it (padding, image size, white space)


visual style guide

Documents