Archive:Tutorial:Creating a glossary page

This tutorial describes how to create a glossary page in Statistics Explained. A glossary page consists of a a short non-technical definition of a statistical or other term used in articles, accompanied by links to more detailed information, to similar items and to relevant statistical data. Its main objective is to provide immediate help to anyone reading an article and coming across a term which is unfamiliar or for which a precise definition is needed (see here for the structure of the overall glossary and the different types of subglossaries).

Besides the English-language 'mother' glossary of approximately 1800 items, less extensive glossaries in other languages are also available, at present: Dutch (Nederlands), Estonian (eesti), French (français), German (Deutsch), Greek (Ελληνικά), Icelandic (íslenska), Polish (polski) and Swedish (svenska). Due to software limitations, some features in other-language glossaries behave differently from the English version. This should not be visible to outside users, but it necessitates some work-around solutions in redirect glossary items; these are explained below.

Functions and characteristics

The glossary of Statistics Explained is a dissemination glossary, targeting the general public, not a collection or database of technical or legal definitions for specialists! Although glossary items are often consulted on their own, for instance by someone looking for an easily understandable and short yet precise definition and entering via a Google search, their first objective is to provide assistance to readers of the statistical and background articles. Any term in an article which might not be readily understood by all or is used in a precise statistical sense (e.g. unemployment) should have a corresponding glossary page.

The Statistics Explained glossary is essentially the online equivalent of footnotes or a text box with definitions or the glossary annex in a traditional paper publication. The

Why create a glossary page?

• The feeling that a term will not be understood by all and needs explaining is the main reason for creating a new Glossary page. The occasion may be your writing a Statistical article, or your reading or revising one, especially when encountering a hyperlink in red to a non-existing page.

Links in red Links in red are non-functional, leading to a page which does not yet exist - or no longer exists. It is an indication of 'work to be done' as well as an invitation to do it, to create the page if it is on a term or concept which you feel needs explaining. On the other hand, never hesitate to put an internal link on any term which in your view should be explained further, even if the resulting link is red and you don't have the time or the competence to create a corresponding Glossary page.(see How to create a statistical article .......create internal link, glossary items) Take a look at existing Glossary items, especially in the subcategory (e.g. Agriculture glossary, Population glossary) your page would belong. Get an idea about their common structure from the model of a glossary page. Length and focus of glossary pages Glossary pages should be short: a reader should be able to find the definition he/she is looking for and be able to get back to the article in less than one minute, with a fuller understanding. This does not exclude that a Glossary page explains more than one term. Sometimes it makes sense to group a limited number of connected definitions, because then relationships and differences show up more easily (see Marriage for an example). Their number must however remain limited, 3-5 items is a maximum. A Glossary page should not become a thematic glossary on its own. Recycling of published definitions and glossary items is a convenient way of getting subject matter. Possible sources are existing glossary chapters of publications such as the Yearbook, a Panorama publication or a SIF; published thematic glossaries (e.g. ); definitions in CODED, Eurostat's Concepts and Definitions Database. But make sure to adapt the definitions to your audience, the general public, and to shorten and reformuletate them more simply if necessary. This is especially recommended for definitions retrieved from CODED, an instrument for specialists getting its content in many cases from legal texts. Structure see Model:Glossary page * Definition: . * Example: only for Nomenclature. * Further (Eurostat) information: links to :* the most recent and much more detailed information available on the Eurostat web site, only metadata! :* it is subdivided in sections, not all of which have to be present in all Glossary pages: downloadable publications pre-formatted main tables (including graphs and maps) database queries dedicated section(s) on the web site other information, including legal texts, manuals, ... The number of items in each of these sections should not be excessive; a maximum of 10 is recommended. * Related concept or indicators : discusses the policy and other reasons behind the data collection and the uses for the data: the legal basis, the policy context, why society as a whole or particular groups (business, policy makers, ...) need them. * Statistical data: to ONE and only one Statistics Explained Statistical article, the most relevant one, as to statistical data, for the glossary item. Definitions of terms and concepts As a rule, definitions should not be in a Statistical article: not in the text itself, not in a separate 'definition box' and not as part of 'Data sources and availability'. A definition should be in a separate Glossary page, in the 'Background area', for several reasons: * Definitions interrupting a text make it longer and more difficult to read (especially for readers already familiar with it). * A separate Glossary page can be linked to from any Statistical article where the term is used, thus avoiding duplication and minor or major differences in definition. * By putting the Glossary page in the category 'Glossary' it is automatically added to the alphabetical list of all Glossary items. See also: #Inserting_an_internal_link Creating a new glossary page Start a glossary page To create a new page in Statistics Explained: type the name of the new page (preceded by 'Glossary:'!) in the 'Search' box on the top left of any page and (left top) and click 'Go' (you may have to click 'ESC' first to remove the roll-down menu) OR insert a glossary link (see Wikitext editing buttons, Glossary link) in an article to a glossary page which does not yet exist and click the red link in the saved draft; a page 'Creating Xxx' opens (Xxx = name of the new glossary page), with this message: You have followed a link to a page that does not exist yet. To create the page, start typing in the box below ...; load the model of the glossary page: As a first step in creating a new Glossary page, you can load the available model for a Glossary page from the boilerplate; it already contains the predefined structure and all templates which might be useful. WARNING: loading of a Model from the boilerplate will overwrite all existing content! If you want to preserve already existing content, select and copy it, load the Model:Statistical article and then paste it in. If you have inadvertently overwritten something, you can always go to 'history' and roll back or undo. Steps to follow: open the menu under 'Select boilerplate' in the box above the edit pane; select 'Glossary page'; click 'Load'; click 'Save page' (just below the edit pane, left), or edit the page and then save. If you create a new internal link in an existing page (see below, 7.1) towards a page which does not yet exist, the linked word(s) appear in red; clicking on the new link will lead you to 'No page title matches' in red, with the possibility to click on 'create this page'; the title of the page to be created is made up by the word(s) on which you put the internal link (See 7.1). Glossary page names Use the conventional and standardised name of a concept, indicator or survey. Take a look at existing Glossary pages for examples, especially in the thematic glossary it belongs (see list of theme categories). Glossary pages start with a capital letter, but the rest of the name is in small letters (e.g. Labour force survey); the only exception are 'official' names of institutions or organisations which are always written with more capitals (e.g. 'European Union', International Labour Organization, Kyoto Protocol). Glossary entries which consist of multiple parts and have a conventional and frequently-used abbreviation are noted with the abbreviation included between brackets, in capital letters,as 'Multiple name (MN)'; for instance 'Livestock unit (LSU)'; the abbreviation (in this example LSU) is a redirect to the complete form and it is also in the same theme category as the full form (in casu Agriculture glossary), but not in 'Glossary' - it is in the Glossary subcategory 'Abbreviations' instead. The form without the abbreviation between brackets (for instance 'Livestock unit') is also a redirect page to the complete form, but this one is not in any category). Inserting content You can of course write an entirely new 'statistical story' about a given data set, filling out the Model you imported. But if you want to convert an existing publication or part of a publication into Statistics Explained format, you only need to copy the text to be inserted insert from the original publication (a Word document, pdf file, a web page, ...) and paste it in the appropriate place within the Model. All existing publications can be downloaded from the publications section of the Eurostat web site or from the EU Bookshop. The text you have inserted normally needs no additional formatting, except maybe in a very basic way (bold, italic, indents, headings etc.). By clicking on the icons above the editing frame, selected text can be immediately converted into bold or italic, an internal or external link can be put on it (don't forget http:// prefix in an external link !) or a level 2 headline can be created. See the summary page of the most common formating code. Check if some slight rephrasing or re-orginazing of the text might not be advisable (replacing 'chapter' or 'publication' or 'Statistics in focus' with 'article', for instance). the material for this chapter can usually be found in methodological notes discussing where and how data were obtained, possible problems with availability (countries or years missing, for example) or comparability issues (e.g. different definitions or data collection methods in different countries). Definitions should not be in Data sources and availability of a Statistical article, but in a separate Glossary page Inserting links in text Inserting links is a way to connect your Statistical article internally (within Statistics Explained) to other articles or to the Glossary, but also to interesting external information, on the Eurostat site or elsewhere. Inserting an internal link A link is 'internal' if it connects to another page within Statistics Explained. The most common case is a link in a Statistical article leading to a page in the background area, usually a Glossary item, briefly and simply explaining an indicator, concept, survey or nomenclature. To insert an internal link: Go into 'edit'. Select the word or words in the text you want to put a link on. Click on the 'Internal link' icon Ab, third one in the icon list above the edit frame (as a result the selected words are put inside of [[ ]]; it is possible, of course, to do this manually). Click 'Save page', bottom left of the page. If the selected words correspond to an existing page, the link is immediately operational. If this is not the case, they appear in red in 'page' view and now several possibilities exist: You can rewrite the linked words in such a way they do refer to an existing page (e.g. 'EU-27' instead of 'EU 27' or 'Life expectancy' instead of 'Life Expectancy' - except for the first one, words in a link are case-sensitive!). You can create a new Glossary page, if you think the concept needs explaining. You can redirect from the linked words to an existing page which is synonymous, by creating a 'redirect page'; redirect pages have as only content: #redirect [[Glossary:name of the destination page|]]. The page 'EU', for instance, contains as only content: #redirect [European Union (EU)]. And finally, the most flexible solution is to link to an existing page while showing in 'page' view a different text, by using [[Glossary:Page name|Text to be shown]]. E.g. the Union instead of European Union. However, an internal link to a 'special' page (such as Model, Tutorial, Category, ...) containing free text should include ':' at the beginning: [[:Tutorial:Governance rules|Governance rules]] returning Governance rules. Inserting an external link A link is 'external' if it refers to a web page outside of Statistics Explained, either on the Eurostat web site or on other 'external' ones. To insert an external link: Go into 'edit'. Select the word or words in the text you want to put a link on. Click on the 'External link' icon (with globe), fourth one in the icon list above the edit frame (the selected words are put inside of [ ]; it is possible, of course, to do this manually as well). add the url you want to connect to, at the beginning and separated by a space from the selected words: [http://xxx selected words]; do not forget to include http:// ! The selected words should be a user-friendly label of the target page of the URL, as specifically as possible. Click 'Save page', bottom left of the page. Example: [http://www.who.int World Health Organization (WHO)] returns World Health Organization (WHO). Inserting and displaying images Images in the form of tables, figures or maps are used in statistical and background articles and on the Main page, but only very exceptionally in glossary pages: they would make items too long and distract from the definition part. Pictures (photographs or drawings) are never inserted just for illustration, only in the very rare cases when they provide additional information. However, in some cases an image can provide valuable and concise extra information in a glossary page; the clearest example is a map in and The procedure to insert image files (tables, figures, maps or pictures) in Statistics Explained and to display them properly in an article, consists of three distinct steps: create image file, normally png, of sufficient size (in pixels), usually from an Excel source or, alternatively, from Word, PDF, web page ...; upload this file in Statistics Explained; insert image link in the article specifying where and how the image file is to be displayed there. How this can be done in practice, is explained in detail in a tutorial on inserting image files. Further information See sections of 'Statistical article'. There is no difference in markup code between linking to another part of the Eurostat web site and to an external web site. Procedures are identical, as a result, for 'Further Eurostat information' and 'External links'; links in 'See also', however, are internal links, within Statistics Explained. Whenever possible, templates are used, so that changes needed are minimal and usually consist of codes or short descriptors. Publications The Model (in edit mode) contains the template (including bullet) * {{Template:Publication|code=KS-RA-07-002|title=Title of the publication}}. Replace 'KS-RA-07-002' with the publication code of the publication you want to link to; if you don't know the code, you can find a list of recent publications or search for it on the publications section of the Eurostat web site. Replace 'Title of the publication' with the exact title of the publication. Duplicate the line with copy/paste and change it accordingly for any further publications you want to add. Save page. e.g. * [http://ec.europa.eu/eurostat/product?code=KS-SF-08-108 Acquisition of citizenship in the European Union – Statistics in focus 108/2008] returns Acquisition of citizenship in the European Union – Statistics in focus 108/2008. It is recommended not to have more than 10 links to publications. Other information In this section all information other than Publications, Main tables, Database and Dedicated section can be inserted. Examples are Regulations and other legal texts, communications from the Commission, administrative notes, Policy documents, manuals and instructions for respondents, ... Regulation 1737/2005 Directive 86/2003 Commission Decision 86/2003 For other documents such as Commission Proposals or Reports, see EUR-Lex search by natural number Adding links to other web sites (External links) As an extra service to users (and to enhance the 'linkedness' and thus the google ranking) links can be provided to a limited number (not more than 10) of high-quality links to trustworthy (semi-)official external sites (e.g. WHO, ILO, FAO, ECB, UNECE, OECD or NSIs). The links should be as specific to the subject treated as possible and they should be deep links directly to the interesting information, not to the home page! The Model you loaded from the Boilerplate already contains the formatted line (including bullet) * [http://xxx Name of organisation/web site/deep link]<nowiki/> * Replace 'http://xxx' with the URL of the deep link into the external web site. * Replace 'Name of organisation/web site/deep link' with a user-friendly label or description of the target page of the URL, accompanied by the name of the organisation between brackets (abbreviated if familiar). e.g. <nowiki>* [http://www.who.int/whosis/database/life_tables/life_tables.cfm Life expectancy: life tables (WHO)] returns Life expectancy: life tables (WHO) If more external links are to be inserted: Copy & paste the line in the template, including bullet (*). Change the new line accordingly. It is recommended not to have more than 10 external links. Related concepts Adding a link to another article is similar, of course, to Inserting an internal link, see above. The Model you loaded from the Boilerplate already contains the formatted line (including bullet) * [[Glossary:Name of related article|]] Go into 'edit'. Replace 'Name of related article' with the name of the article you want to add a link to. Warning: The name has to be exactly right, including capital/small letters and special characters such as / _ etc.) You can of course type this manually too (or, alternatively, type or copy in the name of the article, select it and click the 'Internal link' icon Ab, third one in the icon list above the edit frame). Click 'Save page' (bottom of the Edit page, left). If you want to link to more articles, copy & paste * [[Glossary:Name of related article|]], including bullet (*); replace 'Name of related Statistical article' with the name of the other article. It is recommended not to have more than 10 links to other article; to link only to Statistical articles or Background articles, not to glossary items. Assigning a glossary page to categories Assigning glossary pages to a topic and unit Unlike articles, individual glossary pages are not assigned to a unit, because this would increase enormously the number of pages a Unit is responsible for and would drown out the basic responsibility of a Unit, its Statistical and Background articles, in a huge number of relatively stable and less critical Glossary pages. Instead, theme glossaries are assigned as a whole to the Unit responsible for the topic or topics covered by the Unit. There is a fairly good mapping of topics and theme categories, but at the level of individual Glossary pages there is some overlap: some Glossary pages are in two or more theme categories (e.g. 'Earnings' is in the 'Economy and finance glossary', 'Labour market glossary' and 'Living conditions glossary'), but even then it is usually quite clear which is the main one (in this case: Labour market glossary). The 'Economy and finance glossary' covers so many different topics it cannot be assigned to one Unit, so it is assigned to Unit Dissemination. But practically all items in it also belong to another theme glossary which is their main one. Assigning a theme glossary page is done by placing it into a topic category. Topic categories, starting with X_, are internal categories, hidden from outside users and only visible in edit mode. Each page must have exactly one topic category. This topic is linked to the responsible Unit via a template; in case of a reorganisation or renumbering of Units, it can be changed in this template and all pages and theme categories will be automatically re-allocated to the new responsible Unit. To allow users to find similar articles easily, each article must be put into one or several categories (see the list of current categories). A Glossary page has to be put in the Category 'Glossary' for it to appear in the alphabetical list (unless it is an abbreviation, then it has to be in 'Abbreviations' only). Additionnally, it is useful to also include it in specific subsets of the Glossary: General indicator, Nomenclature, Statistical indicator, Statistical concept, Survey. The difference between general indicator, statistical indicator and statistical concept is sometimes subtle, but also not terribly important. The categories 'Nomenclature' and 'Survey' (and its synonym 'Data collection'), on the other hand, are quite distinct and very useful. Categories for Glossary pages Categories are user-oriented ad hoc groupings of similar articles. They serve as a navigation aid making it possible to find other articles possibly of interest. * Nomenclature: xxx * Statistical concept: xxx * Statistical indicator: xxx * Survey or Data collection: xxx Glossary pages are not put in the themes and subthemes, which are reserved for Statistical and Background articles only; because of their large number they would clutter up these categories and make it impossible to find the statistical pages. Categories are always in alphabetical order. The number of categories has no limit in theory, but categories should only be added if they offer a real service to users for finding similar articles. Replace at the end of the Model Statistical article '<Category name(s)>' (do not forget to remove the comment markup < > as well!!!) in [[Category:<Category name(s)>|Creating a Glossary page]] with the name of the appropriate theme or subtheme (capital letter at the beginning!). For the exact names and hierarchy, see the list of statistical themes and subthemes. If you want to put the article in additonal categories, copy and paste [[Category:<Category name(s)>|Creating a Glossary page]] after the first one, separated by a blank, and change it accordingly. A category which does not yet exist, appears in red in 'page' view. To create it: click on it add a very brief description of one sentence only in the text frame; save it. A category with only one article is not a problem if it is likely to contain more in the future. Example for Statistical article 'Transport infrastructure': [[Category:Regions|Creating a Glossary page]] [[Category:Transport|Creating a Glossary page]] . Validating a page You don't need to do anything for this. The wiki system automatically notifies administrators of any new article or change in an existing one. Old and new versions can very easily be compared and the quality of the changes evaluated. The Statistics Explained Governance rules provide for a quick validation by B6 Dissemination, accepting and making public small changes immediately and sending significant content changes not from the unit owning a page to the unit owning it for validation. All Statistical articles are the responsibility of one unit. Validation should be rapid. Special cases Glossary redirect pages Multiple glossary pages summary, to be elaborated: ideal case is one glossary page, one term (in bold); in two cases there may be more term in a glossary page (which are then redirect pages to a content page, also in all glossary and subglossary category pages): synonyms or abbreviations mentioned in content page one definition building on another: more economical; but: don't exaggerate=user-unfriendly! not more than 5 or so per content item; if more: split it up into separate items Other-language glossaries Besides the English-language glossary of approximately 1800 items, more limited glossaries in some other languages are also available: Estonian (eesti); Dutch (Nederlands); French (français); German (Deutsch); Greek (Ελληνικά); Icelandic (íslenska); Polish (polski); Swedish (svenska). Both the number of languages and the items each one contains are likely to expand. Due to technical limitations some features in other-language glossaries behave differently and somewhat less user-friendly than in the English one; editing aspects of this are explained below. Two procedures are being used to create and update other-language glossaries: the glossary items used in the German and French versions of the Yearbook and Regional yearbook articles were translated into those languages by DGT and inserted in Statistics Explained; in the framework of the ESS glossary pilot project, items were created directly in Statistics Explained by volunteering national statistical institutes, deciding freely on items selected and timing (see above for available languages). Content glossary pages Like with statistical articles, the pagename and url of other-language glossary pages is the English pagename plus '/language code' (e.g. Glossary:Biodiversity/de) but some elements have to be adapted manually: on top a level-1 heading, including 'Glossar:' or 'Glossaire:', etc., the equivalent of the English pagename (e.g. '=Glossar:Biologische Vielfalt=' for 'Glossary:Biodiversity/de'); at the bottom in the second part of the category links the name to be displayed in the glossary category pages, but without 'Glossar:' (just the item name: [[Category:Environment glossary/de|Biologische Vielfalt]]; adding '__toc__' in the text, on the other hand, is not necessary as glossary pages have no table of contents. For regular glossary pages in other languages, this results in near-perfect glossary items with only one minor defect: the categories at the bottom are not displayed as 'Energieglossar' but as 'Energy glossary/de', not totally user-friendly. Redirect pages However, for redirect pages which include abbreviations and may constitute up to 25% of all glossary items, there is a problem. Although they function perfectly for redirecting (e.g. Glossary:EU/fr=>Glossary:European Union (EU)/fr=Glossaire:Union européenne (UE)), it seems impossible with the present Mediawiki version and tools to display them properly in a glossary category page: 'EU/fr' is shown rather than 'UE' which totally destroys the usefulness of a theme category page or a list of abbreviations. So until this is solved technically, an alternative approach has to be taken for non-English redirect pages (taking UE=>Union européenne redirect as an example): instead of 'Glossary:EU/fr', a pseudo-English redirect page 'Glossaire:UE' is created (in a new namespace 'Glossaire:', 'Glossar:' etc); adding level-1 heading is not necessary, the page already has the name which should and does appear on top; the item name to be displayed has to be added manually, like with the normal other-language glossary pages: [[Category:Abbreviations/fr|UE]]; There are some disadvantages: there is no link, like for other pages, with the equivalent in other languages - this is not a big problem as users normally do not see this page but the destination page where other-language versions can be accessed in the normal way; as this is an ad hoc solution not consistent with the way languages are handled elsewhere, the items should be moved as soon as the technical problem is overcome, to the proper page name 'Glossary:EU/fr'; this will not involve too much work as the content itself need not change the display in the category pages is better but still not optimal: instead of 'UE' as should be the case or 'EU/fr' in the unacceptable standard way, it is displayed as 'Glossaire:UE' mixed with regular items not preceded by 'Glossaire:' but in the proper alphabetical place. Weighing these disadvantages against the urgent need for the redirect pages and the probability that a solution will not be fast and easy (possibly needing new version of Mediawiki, at the earliest by mid-2013), the next best solution is to be implemented. Final checklist definition not too long ('completeness' is not an argument!) not too technical, jargon? (conformity to Regulation or methodological manual is not an argument!) not too many definitions in one glossary content page?