Knowledge Maps & Controlled Vocabulary Editorial Manual

THL Toolbox > Reference > Knowledge Maps & Controlled Vocabulary > Knowledge Maps & Controlled Vocabulary Editorial Manual

Knowledge Maps & Controlled Vocabulary Editorial Manual

Contributor(s): David Germano, Steven Weinberger

Introduction

Knowledge maps in this context signify hierarchical representations of a phenomenon or topic. There are top level categories, and then each category can have subcategories, which can in turn have their own subdivisions. These thus function as systematic “maps” of a given topic or area of knowledge. Such knowledge maps can be very helpful to present the breadth of a given area, and help people orient themselves as to the full scope of the domain in question. Of course such maps are artificial to a degree, but this is true of all linguistic representations of an area of knowledge. Thus we are building knowledge maps for such areas as literary genres, geographical features, languages, religious sects, animals, and much more. These knowledge maps are not only helpful for readers to visualize the area and understand its various subareas, but we also utilize the knowledge maps to index THL resources. Thus as you look at a knowledge map, you can not only see a short description of each category, but you can also see whatever THL resources pertaining to it might be available – essays, texts, photos, images, audio-video, projects and so forth. In addition, labels for each node are potentially available in other languages.

Each knowledge map generally has a “curator,” which is a person, or people, who are responsible for watching over that knowledge map, making adjustments, finding contributors, determining which descriptions are primary if there are more than one description for a given category, and if necessary addressing disagreements about the hierarchy itself, or when descriptions are not of sufficient scholarly content. The categories or subcategories of a given knowledge map can also have curators, but should only be when there is good reason for that part of the hierarchy to have a curator independent of the overall curator of the knowledge map. In addition, every knowledge map in general, and every category and subcategory in particular, can have descriptions. Each can have multiple descriptions, each of which is prefaced by the name of the author(s), and the date it was authored or last updated.

1. LOGIN

To create and edit Knowledge Maps, you need editorial privileges and a login and password. If you want to apply for editorial privileges, please contact us: <a class="safe-contact" href="javascript:linkTo_UnCryptMailto('nbjmup;uimAdpmmbc/jud/wjshjojb/fev');"><img src="/global/images/contact/contact-thl.gif"></a>

Editorial features for creating and editing knowledge maps only appear after you login. Click on the upper right hand corner “login” and you can type in your user ID and password. If you are using a computer that no one else uses, then you can click on the “remember me” check box so that the computer will remember your login/password in the future to make login easier.

Once logged in, the knowledge map web page will have new options added to it that allow you to create and revise. Please be sure to log out if you are using a public computer, or others use your computer. To do so, just click on the upper right hand corner “logout.”

2. CREATING A NEW KNOWLEDGE MAP

Once logged in, you will be shown the Knowledge Map home page, but now after the header “Knowledge Map” you will see the words “add.” To create an entirely new Knowledge Map, click on “add.” In the resultant form,

Enter the name of the Knowledge Map. Use the singular, and do NOT add the words “knowledge” map. Use title case. Thus enter “Tibetan Ritual System” and NOT “Tibetan ritual system” or “Tibetan Ritual Systems” or “Tibetan Ritual Systems Knowledge Map” or any other permutations.
Specify the name of the Knowledge Map’s curator. If there is more than one curator, you can click on “add new curator” to add as many curators as you like.
Click on “create” to create the new knowledge map.

3. ADDING CATEGORIES TO A KNOWLEDGE MAP

Now that the knowledge map is created, you either add a description, or start creating categories and subcategories.

Categories: you can create top level categories by clicking on “new master category” to the right, after which you:

Type in the name of the Category
Specify the name of the curator of the category, if you desire a curator separate from the overall knowledge map’s curator, though you should have a good reason for doing so and generally separate curators are not encouraged for categories
Click Create

Once created you then do two additional things:

add a description, just as detailed above
add a translation of the category name into another language
if there is a source for the category, add a source by clicking the Source button. For example, in the Tibetan Grammatical Functions Kmap, the categories are taken from Manual of Standard Tibetan, so each category will have a source that uses the MMS ID for Manual of Standard Tibetan (999999) and uses for the start page and end page the pagination in Manual of Standard Tibetan for that section.

See below under “Editing” for more details on creating categories and subcategories.

3. THE BASICS OF EDITING EXISTING KNOWLEDGE MAPS

To edit a Knowledge Map, you just click on that Map and you will initially see on the left the name of the Knowledge Map along with the description, and on the right the full list of top level categories.

To edit the name of the Knowledge Map, just click on the “edit” button after the name. You can change the name, and also specify a curator. When finished, click on the “update” button.

If you want to add a new label in a different language for the Knowledge Map, click on “add translation” at the top following the name of the Knowledge Map. That will give you an editing box to type in the translation, and a drop down box where you can specify what the language is. If the language you want to use is not in the list, just contact us and we will add. You can also specify “source(s),” namely the source of this translation. Once you are done, click on “create translation.”

If you want to delete the Knowledge Map, you go back to the page for the Knowledge Map overall, and click on “delete” below the entry. Please NEVER delete a knowledge map unless you just created it and it has no content other than what you put into it.

To create a new top level category, on the home page for that Knowledge Map look down in the lower right hand corner below the hierarchy. You will see an option “New Master Category.” It will give you the same interface detailed above – name, description boxes, with the latter having the same WYSIWYG interface. Fill in the name of your node and a description of it, and hit “create.” That will insert that category at the top level in alphabetical order with the other top level categories.

If you instead want to add a subcategory to an existing category, first navigate your way through the tree to get to the relevant subcategory. Navigation is easy. Categories preceded by the + sign mean they have subcategories; the - sign means they are already expanded in the view; the diamond sign ◊ means they have no subcategories. Once you get to the subcategory for which you want to create a further subcategory, click on the label “new subcategory” which follows each node’s label. Please note you will only get the option to create a new subcategory after you have expanded a category (meaning it shows with the - sign). If a category has a + sign on it, first click on it to expand it, and then you will see the “new subcategory” option. The interface and process for creating a new subcategory is otherwise the same as creating a new top level category.

To edit an existing category, navigate to the category in question so that it is highlighted in the tree to the right. On the left you will see the category’s name and any description. Below it, you will see “edit” and “delete” links. Delete will delete the category, while edit will give you an editing interface to change the name and description. However, there is one new control. You can also change the parent category. Thus if you decide you want to move this category to a different place in the tree, under parent category click on “select.” This will give a popup which presents the entire knowledge map tree with the same navigation controls. Navigate to the new parent category, and then click on the new “select” button at the top. Then click on the “update” button at the bottom, and the category will be moved to its new location in the tree.

If you only want to add a new translation of the category’s name, then navigate to the category on the right, and then in the display on the left, at the top after the name of the category you will see the “add translation” link. Click on it and follow the instructions above to add a new translation of the category’s name.

Details on Category Names

Enter node labels in the singular, not the plural, when writing in English. This allows the application to automatically generate either the singular or plural form depending on the context.

When entering Tibetan for labels for hierarchical nodes, follow each term with a final “shad,” UNLESS the term ends in the letter “ga” (ག), in which case it should be followed by nothing; or if it ends in the letter “nga” (ང), in which case it should be followed by a “tsheg” ( ་ ) and a “shad” ( ། ).

When filling out the “name” field for a node for which you have a Tibetan word but not a good English translation, enter a phonetic rendering of the Tibetan using external link: THL Simplified Phonetics (note: to do this properly you will likely have to add vowels with accent marks, which may mean cutting and pasting from a Word document). Then add the actual Tibetan for the term in a unicode Tibetan font as a translation attached to that name.

When adding an author for THL-Wylie or THL-Phonetics enter the source of the original Tibetan term, not person who made the transliteration or transcription.

4. ADDING DESCRIPTIONS OR ESSAYS

This allows for an infinite number of descriptions or essays to be attached to a given place entry, which can range from a paragraph summary, to a twenty page article. Each article has a title and one or more authors specified. While a single description can be quite lengthy, to facilitate reading over the Web, we suggest authors consider instead submitting lengthy pieces in separate, shorter essays.

Editors are encouraged to try to provide descriptions for each category in a knowledge map, which greatly enhances its value. Please try to write the descriptions in an accessible manner that will be readable and of interest to as many people as possible.

We suggest, when relevant, you indicate bibliographical sources for the relevant categories as well, at least for more obscure items. Please list them at the end of the description. We intend to ultimately provide a more formal way to cite sources using the THL bibliography tool, but this is not yet implemented.

A description is intended to provide an overall account of the scope of this knowledge map, and anything of relevance you want to communicate to end users about it as a whole.

First indicate the language of the description through the dropdown list of languages (if an English-language description contains a list of Tibetan terms use commas rather than shad to separate the terms, for example: ཡག་ག, ཡག་ཤོས་, སྙིང་རྗེ་པ་ལ་, ཆེ་དྲགས་, རིང་ལོས་ or གང་བྱུང་མང་བྱུང་ “anyhow”, ཐ་རེ་ཐོ་རེ་ “scatty, piecemeal”, ཚ་གེ་ཚི་གེ་ “nervous, shaky”, ཚབ་བེ་ཚུབ་བེ་ “hastily”).
Use the rich text editor to type in a description; please see the section below on the editor for details on how to use the text editor to format a description.
Indicate via the checkbox “is primary?” whether this is the primary description attached to the category or not. Whichever description is indicated as “primary” will appear first if there is more than one description.
Specify the name of the author, and if there is more than one author, add the names of the other authors by using the “add new author” button.
Click “Create Description” to formally create the description.
If the description is taken from a source other than yourself, after you have created the description, click the add source button beneath the description:
1. Enter data in the MMS ID field. This functionality is not automated yet, so contact us and we will give you an ID for your source.
2. Enter data in the start page and end page fields, and select the language of the source in the Language pulldown menu.
3. For example, in the Tibetan Grammatical Functions Kmap, the descriptions entered as of 2010-03-01 are taken from Manual of Standard Tibetan, so each description has a source that uses the MMS ID for Manual of Standard Tibetan (999999) and uses for the start page and end page the pagination in Manual of Standard Tibetan for that section.

Each description/essay has a top “title box,” where you insert the title of the essay.

To specify the author, click on the “Add new Author” link at the bottom and chose an author. You can add as many authors as you like. If the author’s name is not on the list, please contact us to add him/her and we will do it promptly.

At the bottom is a checkbox that is used for indicating if the description in question should be considered the primary description. If you check it, then this description will become the primary description, and will be located first in the list of descriptions for this place, if there are more than one descriptions. The primary description should be a general introduction to the place, not a focus on one aspect of the place, or a highly interpretative essay.

We suggest first using a word processor to brainstorm on your hierarchy of categories and subcategories, and then cutting and pasting the results into the knowledge map application. For example, if you use Microsoft Word, using “headers” at different levels (h1, h2, h3, etc.) and the outline view, you can efficiently create, visualize and revise hierarchies without the delays involved in doing extensive revisions on any Web application, including THL’s Knowledge Map Builder. When deciding on the hierarchy, you must balance trying to make it as detailed as possible on the one hand, with the need to make it actually usable in categorizing real world phenomena. For example, you might make such fine tuned categorizations, that very few actual phenomena correspond to the categorizations; on the other hand, you might such the categorizations so broad that they lump together too many diverse phenomena that could be easily differentiated.

The Editor for Descriptions/Essays

The WYSIWYG (“What You See Is What You Get”) rich text editor for descriptions and essays is a THL editor that is used across THL in many applications. For that reason, we keep its documentation separate so that a number of editorial manuals can refer to it. For anyone writing descriptions, it is essential that you refer to the THL Online Essay Editor Manual for details on how format your text and use the editor.

Exporting a Knowledge Map into a CSV File

Microsoft Excel can't read diacritics in the CSV file that is exported under the current export system. To view the diacritics in the file:

If you don't have OpenOffice installed, download and install it (free) from http://www.openoffice.org/download/index.html
If you don't have the free Jomolhari-ID font installed download and install it from the link on this page: http://www.thlib.org/tools/scripts/wiki/Jomolhari%20ID.html
Go to subjects.thlib.org and press the name of the Knowledge Map you want to export into a spreadsheet (make sure you have pressed the top-level category for the knowledge map)
At the bottom of the left part of the screen, press "Export to CSV"
Right-click on the file and open it with OpenOffice
In the dialog box that opens:
1. make sure Character Set=UTF-8
2. in the "Separated by" section select Comma and unselect everything else (Semicolon, Space, etc)
3. in "Text delimiter" make sure it has " (if it does not, pull down the menu and select ")
Name the file the same name as the Knowledge map, like religious-sects; press OK
Pull down the Edit menu and select "Find and Replace" (the keystroke to do this is probably command-f for Mac and probably ctrl-f for Windows).
In the "Search for" box enter & quot; (but without the space between them)
In the "Replace with" box enter nothing (the box should be blank)
Press "Replace All"
Do the same operation but in "Search for" enter: & amp; (but without the space between them) and in "Replace with" enter: &
Do the same operation but in "Search for" enter: & #x27; (but without the space between them) and in "Replace with" with enter: '
Highlight the Tibetan column and do the following:
1. In the Font pulldown at the top left, select Jomolhari-ID.
2. Right-click in the highlighted column and select Format Cells. Then press the Alignment tab, pull down the Vertical menu and select Middle
Add a new column for each of the translations you will add. For example, a column that in row 1 has the label "Chinese-Simplified" and a column that in row 1 has the label "Chinese-Pinyin"
If you are also translating the descriptions of each category, add a column with the label "Description-Chinese-Simplified" in row 1. NOTE: the English description will not be in the spreadsheet file; you will need to get that from the online application itself.
Save the file; it is now ready to add translations.