MuDoc Help

If this is your first time visiting this page, please read the first few sections. If you're here seeking documentation on a particular MuDoc page, click on the page name to be taken directly to relevant help.

definitions

graphs, keywords, ontology

• graph: a set of nodes and links connecting them. More precisely, links are defined as pairs of nodes. (In mathematical graph theory, nodes are called vertices, and links are called arcs.)
• directed graph: a graph in which links have direction (pointing 'from' the first node 'to' the second). The starting node may be termed the "parent" of the ending node, its "child". (Mathematically, such links are 'ordered' pairs, comprising a first and second element.)
• acyclic directed graph: a directed graph in which there are no loops (it is not possible, from any vertex, to trace a continuous path by always moving from parent to child node (then to the child's child node, and so on), and finally return to the starting point. In such a graph, every node (except root nodes) has one or more parents, and may have one or more children as well. The acyclic condition implies that no node is an ascendant (or descendant) of itself. Root nodes (by definition) have no parents. There must be at least one root node (since otherwise there would be a loop). Such a graph is connected (comprises one 'piece') if there is only one root node. A connected graph is one in which every two nodes are connected by a continuous path (provided that path is allowed to traverse directed links in either direction).
• directed acyclic graph (dag): acyclic directed graph
• directed tree: an acyclic directed graph in which each node has one and only parent. The folder hierarchy (disregarding "shortcuts") on your PC or Mac is an example of a directed tree. Another is the asset hierarchy on MuDoc's Submit page (see below).
• (MuDoc) keyword: a textual word or phrase naming a node in a special dynamic dag called the "MuDoc Ontology" (see below). Each keyword represents a concept with a semantic extension in the world. Thus a keyword is a tripartite structure: text name; node; concept. Because keywords occur within a dag, each keyword (except the root) has at least one parent, and may have children.
• Ontology: "...a data model that represents a set of concepts within a domain and the relationships between those concepts" (from Wikipedia, Ontology).
• MuDoc Ontology (a): the directed acyclic graph comprising all MuDoc keyword nodes. The MuDoc Ontology is a connected dag, with a single root node (also called MuDoc Ontology). The semantics of this dag are as follows: to state that MuDoc keyword X is the parent of MuDoc keyword Y is to assert that the extension of Y's concept is a subset of the extension of X's concept. These assertions ought to be plausible, if the dag is to be usable. For instance, keyword "Africa" could, by general agreement, be admitted as the parent of keyword "Cairo". Keyword "Middle East" might also be admitted as parent of keyword "Cairo". (Technically, keyword "Europe" could be set as parent of keyword "Cairo", but this assertion is harder to justify.). Thus if X is a keyword, the following interpretions obtain:
  • X's parent: a keyword whose concept includes that of X ("broader term")
  • X's child: a keyword whose concept is subsumed within that of X ("narrower term")
• MuDoc Ontology (b): the name of the root node of this graph (a better name would have been "MuDoc Ontology root").

assets and metadata

• asset node: a MuDoc entity to which metadata, keywords, a digitial asset, and digital rights can be attached
• asset links: links between asset nodes, of three types (1) parent-child links; (2) annotation links; (3) collection links; (f) general relation links. Parent-child links are used, for instance, to represent the relation between an album and its tracks. Annotation links define the relation between an annotating and annotated object. Collection links define an object in relation to a dynamic collection, to which periodic submission is always possible. General relation links can be used as "see also" pointers.
• asset: a digital object of any sort
• annotation: an asset with an annotation link.
• metadata: asset attributes, each associated to fixed fields called metadata elements.
• metadata schema: a set of metadata elements applied consistently to a set of digital objects. MuDoc is designed to support any number of metadata schemas.
• Dublin Core: one particular metadata schema, designed for online interoperability. At present, Dublin Core is the metadata schema provided in MuDoc.

roles

• user: anyone registered to use the MuDoc system, defined by username, password, and profile. A user may also be a reviewer or editor.
• reviewer: a user assigned to review submissions falling under the semantic extension of particular keywords in the MuDoc Ontology. Each reviewer is thus associated with one or more keywords for which he or she reviews.
• editor: a user assigned to edit submissions falling under the semantic extension of particular keywords in the MuDoc Ontology. Each editor is associated with one or more keywords, for which he or she edits. The editor for the root keyword ("MuDoc Ontology") is known as the Editor in Chief (EIC).

processes

• submission: there are in effect three kinds of user submissions: (1) asset submissions, structured as directed trees in which each node may be associated with an asset file, metadata, and keywords. The asset submission's root node must have at least one associated keyword (for peer review). (2) keyword submissions. Each such keyword is associated with existing keywords proposed as its new parents. (3) role-requests (effectively self-submissions). Here a user submits herself or himself to become reviewer or editor for a specific keyword. (Role-requests are presently not handled on the "submit" page, but logically they should be.) All submissions are peer-reviewed.

• peer-review: process by which submissions (including role requests) are evaluated by an editor, in consultation with a set of reviewers. In brief the process works as follows: (1) user makes submission, associated with particular keyword(s); (2) MuDoc requests closest available editor to handle this submission; if this editor refuses or doesn't respond within a fixed time window, another selecction is made, until finally the request passes to the EIC, if necessary (the EIC cannot refuse requests); (3) the editor reviews the submission and requests a number of appropriate reviewers, who are also selected on the basis of keyword associations, in a process parallel to that of editor selection; (4) reviewers provide feedback; (5) editor makes final decision (accept, reject, or return with comments).

how-tos

• how to know navigate the system. The MuDoc interface is divided into a number of pages: "Login", "Home", "Request Role", "Profile", "Editor Review", "Review", "Search", "Search History", "Submit". The name of the current page is always provided at the top of the screen, to the right of the MuDoc logo. You always start at the "Login" page, and upon successful login are moved to "Home". From here you select the page corresponding to the action you wish to perform by clicking on the links appearing just below the MuDoc logo. Select:
  • Home to handle messages in your inbox, request a role, or update your profile.
  • Home to request editorial or reviewer roles.
  • Editor to perform the editor role
  • Review to perform the reviewer role
  • Search to locate assets, by keyword or metadata
  • Search history to review search results
  • Submit to submit new assets or keywords, and to link new assets to existing assets
  • Logout to exist

• how to search and browse the MuDoc keyword ontology. Searching and browsing the MuDoc Ontology is required in several places (request role; search; submit), always using the same interface, comprising a writable text box, "find" button, and list of selected keywords. Searching and browsing are integrated. Selectable keywords are displayed in dark blue, their parents and children in light blue. Clicking "find" with no text in the text box renders the root node ("MuDoc Ontology") selectable (this is admittedly not intuitive; a better way is coming soon). Clicking "find" with any other text string in the text box searches for the string within the set of all keyword strings, and renders text matches selectable. All displayed keywords are hyperlinks. Selectable keywords are displayed in dark blue, surrounded by parents (above) and children (below). Clicking a selectable (dark blue) keyword selects it, transferring it to the selected keywords list for further action (e.g. search, submit). Clicking a non-selectable (light blue) keyword brings it into the "selectable" position, displaying a new set of parents and children. Browse the dag by clicking on a parent or child keyword.

• how to search the system by metadata or keywords. See documention on "search page", below.

• how to submit new content. See documentation on "submit page", below.

• how to become an editor or reviewer. See documention on "home page", below.

• how to perform editorial or reviewer roles. See documentation on "home", "editor" and "reviewer" pages, below.

Login page

• to login: enter username and password, and click "submit" (note that passwords are sent clear at present, unprotected by https; do not use reuse important passwords )
• to register: click "Not registered?" and follow the instructions. Please enter your real name, as anonymity is not helpful except where enforced by peer review. Enter an email you will actually read. Set your availability, and enter a note of explanation below.

Home page

Inbox

• click on a radio button to read the corresponding message
• respond by clicking "accept" or "decline" when appropriate
• click on inbox controls to view all messages, or page through messages
• click on inbox conrols to order messages by date, subject, or status ("closed" messages have been dealt with; "open" messages have not).
• if you've agreed to edit or review a submission, be sure to visit the editor or review pages next.

User tasks

• click on "request a role" to propose yourself as editor or reviewer for a particular keyword (see "request role page" below)
• click on "edit profile" to edit information you provided upon registration. Please remember to keep your availability attribute up to date.

Request role page

1. select role (editor or reviewer) from drop-down menu
2. add statement: summarize qualifications, include a URL for your CV, etc.
3. specify a keyword by browsing or searching the keyword ontology (you can only request one keyword at a time).
4. submit request, or cancel to abort the operation
5. your request will now pass through peer review (according to the keyword you selected); you will receive confirmation messages in your inbox.

Editor page

1. select tab corresponding to the editorial task you wish to perform
2. click "refresh" to update the page
3. select the asset, keyword, or role submission you wish to review by clicking on it (on the left)
4. view details on the right
5. follow steps 1-6 below (select reviewers, await feedback, issue final editorial decision).

Review page

The procedure for reviewers closely parallels the procedure for editors; see "Editor page" for instructions. The principal difference is that reviewers are only offering recommendations, and are not permitted to know the identity of the submitter except in the case of role-requests (in which case the submission is effectively the submitter).

Search page

1. select the tab corresponding to the search task you wish to perform. Search by keyword allows you to search/browse the MuDoc Ontology, select a set of keywords, and execute a search (a boolean AND is implied). Keyword searches may be recursive or non-recursive. A recursive search for keyword "Africa" implies a semantic (conceptual) interpretation of the keyword, and returns all assets marked with keyword "Africa" or marked with any keyword which is a descendant of "Africa" (and hence--according to the standard semantics of the keyword dag--whose real-world extension is a subset of the extension of "Africa"). A non-recursive sesarch for keyword "Africa" implies a syntactic interpretation of the keyword, returning only those assets actually marked with keyword "Africa" (but not returning, for instance, assets marked with "Ghana"). Note: recursive search is coming soon.
2. select keywords or metadata attribute/value pairs, as appropriate
3. execute search
4. click "view history" (or "Search History")
5. click to view search results, including metadata and keywords, or delete them
6. click to browse from an asset (following links to parent or child assets, to annotation assets, or to other linked assets) Note: this feature is not yet implemented.
7. click on the title of a result to download the asset (if allowable)

Note that the search history is maintained across sessions as a permanent part of your user space; you can delete results which are no longer of interest. Note that as the repository is dynamic, a search result may become outdated.

Search History page

Search history has been explained above; see "Search page" for instructions.

Submit page

The submit page allows the user to submit assets and keywords; submission of roles is handled via the Home page.

• Begin by selecting the tab corresponding to your submission (asset or keyword).

• Submit "Assets" tab

1. click "Add" to add a new node (by default entitled "NEWITEM") to the asset hierarchy (displayed in tree form at the left).
2. click this new node to select it.
3. enter information, asset, metadata, and keywords pertaining to this node using the form to the right.
   1. Top section: title, description, cultural, quality, authenticity. These fields and drop-down selecdtions are not technically metadata (they are not searchable). The "title" field replaces "NEWITEM" to become the node name.
   2. Top section digital rights controls: downloadable, price, visible. These fields should be filled in whenever an asset is attached. They are searchable as metadata. Check "downloadable" to allow downloads. Check "price" if you wish to charge a fee for downloads. Check "visible" to make metadata visible, but prevent downloads (this section needs fixing).
4. attach an asset if desired
5. select a metadata model; at present only Dublin Core is available.
6. add metadata attributes and fill in type (attribute) and value pairs.
7. select keywords
8. back at the top of the form, click "save" to save all information to the selected node.
9. click "Add" to add subnodes (recursively) and repeat the above process until the submission hierarchy is complete. Be sure to click "save" for each node or information you entered will be lost. The full submission is a directed tree, in which each node (except the top node) has one parent, and each node may have one or more children.
10. select any node and click "Submit for review". Note that you need not submit a "top level" directory node; you can submit any node. If the submission contains no technical problems, it will disappear from the asset hierarchy. This means the submission has entered peer review. Check your inbox for further information regarding the status of your submission.

NOTE: When you click "save" for a particular node, its description page will disappear. If you wish to submit it, you will have to select the node again.

NOTE: in the near future it will be possible to define links from new assets to existing assets, to be interpreted as "annotation", "part of collection", or "general relation".

• Submit "Keywords" tab

1. add nodes as described under "Submit Assets". Each node represents a keyword
2. enter information and justification using the form to the right.
   1. keyword: name your keyword
   2. reason: justify the need for this keyword and its positioning within the Ontology
   3. select parent keywords. Note that you can select more than one parent. However it is not possible to select children, i.e. you cannot position your new keyword within the existing ontology, but only at its edge.
   4. click "Save" to save your information
   5. select any node and clikc "Submit for review", as for assets. If the submission contains no technical problems it will disappear from the keyword hierarchy and enter peer review.

see also

• MuDoc FAQ
• MuDoc system