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)
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.
Structure
* 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:
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.
Creating a new glossary pageStart a glossary pageTo create a new page in Statistics Explained:
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:
Inserting contentYou 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).
Inserting links in textInserting 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 linkA 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:
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:
Inserting an external linkA 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:
Example: [http://www.who.int World Health Organization (WHO)] returns World Health Organization (WHO). Inserting and displaying imagesImages 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:
How this can be done in practice, is explained in detail in a tutorial on inserting image files. Further informationSee 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. PublicationsThe Model (in edit mode) contains the template (including bullet) * {{Template:Publication|code=KS-RA-07-002|title=Title of the publication}}.
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.
Other informationIn 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, ... 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:
Related conceptsAdding 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|]]
If you want to link to more articles,
Assigning a glossary page to categoriesAssigning 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.
A category which does not yet exist, appears in red in 'page' view. To create 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 pageYou 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 casesGlossary redirect pagesMultiple glossary pagessummary, 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):
Other-language glossariesBesides the English-language glossary of approximately 1800 items, more limited glossaries in some other languages are also available:
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:
Content glossary pagesLike 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:
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 pagesHowever, 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):
There are some disadvantages:
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
|