TagTeam basics

From Harvard Open Access Project
Jump to: navigation, search
  • Visit the Harvard instance of TagTeam itself.

Preface

Here we describe how to use TagTeam. First we introduce some TagTeam terminology, and then we go through each of the basic tasks you can perform with TagTeam, such a creating a hub, tagging web pages for a hub, modifying tags, subscribing to feeds from outside TagTeam, managing the feeds generated by TagTeam itself, and searching.

TagTeam terms

  • A TagTeam project is a hub. The person who creates the hub is the hub owner. The hub owner can add others to the project and give them various roles or permissions. Hub members with suitable permissions can tag web pages for the hub, modify the tags used by any project taggers, have the hub subscribe to feeds published elsewhere, modify the feeds to which the hub subscribes, and create hub feeds based on any combinations of tag feeds and input feeds.
    • Hub inputs take three forms: (1) tags applied to external web pages, (2) feeds to which the hub subscribes, and (3) tag records imported from other tagging platforms such as Connotea. Hubs store their inputs from all three sources for deduping, back-up, export, modification, and searching.
    • Hub outputs take four forms: (1) an output feed for each hub tag, (2) an output feed for each input feed, without modification, and (3) an output feed modifying an input feed, (4) an output feed combining any tag feeds and/or input feeds, with or without modifications.
  • An item is the unit of TagTeam information. If you tag an article for a TagTeam hub, the item contains the URL of the article, all the tags you and your fellow hub members applied to the article, the "description" of the article you may have added at the time of tagging, the fact that you were the one (or one of the ones) who tagged it for the hub, and similar information. (Hence, we sometimes call items "tag records".) The item does not include the text of the article itself. When a hub subscribes to feeds from elsewhere, those feeds deliver streams of items to the hub. When a hub publishes its own feeds, those feeds deliver streams of items to feed subscribers.
  • The bookmarklet is the button on your browser bar that lets you tag web pages. If you have permission to tag for a hub, then you can find the bookmarklet in the "Bookmarks" tab. Near the top of that page is a rectangular button with the phrase "Add to TagTeam". Just drag that button to your browser bar. If you don't have permission to tag for a given hub, you will not see the button on the hub's Bookmarks tab.
  • A filter is a rule for modifying tags. Hub members with suitable privileges can create filters, for example, to replace deprecated tags with approved tags, to replace misspelled tags with correctly spelled tags, and so on. TagTeam can apply filters to individual items, to individual input feeds, or to the entire hub. Filters can be prospective (modifying all tags made in the future) and retroactive (modifying all tags already stored in the hub). Hub owners can use filters to tidy up a chaotic collection of tags, and to manage the evolution of a folksonomy of user-defined tags into an ontology or standard vocabulary of project-approved tags.
  • A remix feed is a feed published by TagTeam consisting of some combination of other feeds. If your project has many tags, for example, A, B, C, D, and E, then a remix feed could contain just the items with tags A, B, and C, or just the items with A and B but not C (that is, excluding items with C). When we remember that TagTeam can subscribe to any existing feed from elsewhere, that every TagTeam tag generates its own feed, and that every TagTeam search generates its own feed, then we can see the power of remix feeds. TagTeam can create remix feeds based on any Boolean combination of input feeds, tag feeds, and search feeds. Hub owners can carefully craft certain remix feeds and offer them to users. Or users with relevant permissions can create their own.

What you can do without signing up or signing in

  • Without signing up or signing in, you can view all hubs or projects running on a given instance of TagTeam. You can run searches in any hub. You can subscribe to the feeds published by the hub. You can also select any tab on any hub and view its information in read-only mode. But you must create an account and log in if you want to create a new hub or make any changes to an existing hub.
  • You can also request permission to tag for someone else's hub without signing up for an account or signing in. But you must have a TagTeam account before your request can be approved.

Logging in

Signing up and signing in

  • Go to TagTeam and click the Log in link on the upper right corner of the screen.
    • If you already have an account, fill in the Username or email and Password fields and click Sign in.
    • If you do not have an account, click the Sign up link.

Note that usernames may only contain letters, numbers, underscores, and hyphens.

Once you have sign up and an account, you can create your own hubs, tag for your own hubs, add members to your hubs, and give members different rights or permissions.

Changing your account details

  • To change your username, email address, or password, or to cancel your account, first log in. Then go to the "My Account" page and make the changes you want.

Creating a new hub

To create a new hub:

  • Log in to TagTeam.
  • Click the New hub link.
    • Fill in the required Description field. If you like, fill in any of the optional fields for Title, Nickname, Description, and Tags.
    • Click Create hub.

Tagging

Once you have a TagTeam account and have created one or more hubs, you may tag for your own hubs right away. Jump to the section below on adding and using the bookmarklet.

If you want to tag for a hub owned by someone else, you will need the hub owner's permission. Likewise, if others want to tag for one of your hubs, they will need your permission.

Adding and using the bookmarklet

If you have permission to tag for a hub, then you can install the bookmarklet for tagging. A bookmarklet is a button on your browser bar to execute a certain command, usually a command relevant to the page you're currently viewing through the browser. In this case, the command is to tag that page for TagTeam.

To add the bookmarklet to your browser:

  • Log in to TagTeam and go to the desired hub.
  • Click the Bookmarks tab.
  • Drag the Add to TagTeam link to your browser's tool bar, where it will become a clickable button.
    • Note that most browsers let you edit the name of the bookmarklet button, for example, to make shorter and save space on your browser bar.

Once you install the bookmarklet, you can start tagging. The process is simple: When you're viewing a web page that you want to tag for TagTeam, click on the bookmarklet button and fill in the bookmarklet form that pops up.

  • If you mark a block of text before you click the bookmarklet, then that block will appear in the bookmarklet's "description" field. Otherwise the "description" field will be blank and ready for you to fill in.

If you have permission to tag for more than one TagTeam hub, then by default the bookmarklet form will add the item to the most recently selected hub. You can specify a different hub with the drop-down list near the top of the bookmarklet form.

Requesting permission to tag for someone else's hub

To request permission to tag for a certain hub:

  • Log in to TagTeam and go to the desired hub.
  • Click the Contact tab in the left sidebar.
  • On the "Contact the owners of this hub" screen, do the following:
    • Fill in the Name and Email fields. The Name field is optional, but we recommend filling it in. Hub owners are more likely to approve your request if they know who you are.
    • Select "Request to collaborate" from the Reason drop-down list. When "Ways you'd like to collaborate" list appears, check any desired selections.
    • Fill in the Message field to explain your request.
    • When done, click Submit.

The hub owner should then reply to your request by email. Note that these requests must be approved by the human hub owner, and if the owner is busy or traveling, this may take some time. Follow up with the hub owner if you do no hear back within a reasonable time.

Using TagTeam as your tagging platform

If you want to tag for a TagTeam hub, naturally you can use TagTeam itself. This section explains how. But you may also tag for a TagTeam from tagging platforms other than TagTeam. The next section explains how to do that.

To tag for a TagTeam hub using TagTeam itself:

  • Create a TagTeam account if you haven't already done so. After you create an account, you can create TagTeam hubs, tag items for your own hubs, and tag for hubs owned by others if the owners give you permission to do so.
  • To tag for one of your own hubs, create the hub, install the bookmarklet, and start tagging. Go to a web page you want to tag, click on the bookmarklet, and fill in the bookmarlet form.
  • To tag for a hub owned by someone else, request permission and wait to be approved. Then install the bookmarklet and start tagging.

Using a tagging platform other than TagTeam

You can tag for TagTeam hubs from any tagging platform that generates RSS or Atom feeds for each of its tags, for example, CiteULike or Delicious. Suppose you want to use Delicious to tag for a TagTeam hub. The basic idea is that you create a special tag for Delicious which means in effect "add this item to a certain TagTeam hub". Then you ask the TagTeam hub to subscribe to the feed Delicious generates for that special tag.

The primary benefit of this feature is that participants in social tagging project remain free to use the tagging platforms of their choice. They needn't use TagTeam at all, and they needn't agree on any other single platform. As long as they use tagging platforms that generate RSS or Atom feeds for their tags, then a TagTeam hub can gather their project-related tags together in one place and publish new feeds based on their combined inputs.

To tag for a TagTeam hub using another tagging platform:

  • Create a special tag for items you want a TagTeam hub to include.
    • Your special tag may be any string of characters accepted as a valid tag by your chosen tagging platform.
    • It should be a string that other users of your favorite tagging platform are unlikely to use, such as add2hubx, jane-add2hubx, TagTeam14159, or TTzebra.
  • Determine the URL of the RSS or Atom feed generated for your special tag by your chosen tagging platform.
    • If your chosen tagging platform generates a feed for your individual use of that tag, and a separate feed for everyone's use of the same tag, then use the former.
  • Request permission to tag for a given TagTeam hub.
    • In your request, indicate the name of the tagging platform you want to use and the URL of the feed for your special tag.
  • When you are approved, the hub owner can subscribe to the feed generated by your special tag.
  • From your chosen tagging platform, use your special tag for all the items you want the TagTeam hub to include, and omit it from all the items you want the hub to exclude.
  • When you apply your special tag to an item, you may apply any number of other tags as well. If you do, then the TagTeam hub will harvest all the tags you applied.
    • For example if you use your special tag plus tags A, B, and C, then TagTeam will add the item and mark it with your special tag plus tags A, B, and C.
  • If you use your special tag for too many items unrelated to the hub topic, the hub owner may unsubscribe from your feed.

One purpose of a TagTeam hub is to publish carefully curated feeds relevant to the hub topics. Hub owners who notice spamming can revoke the spammer's permission to tag for the hub.

Tagging items that have already been tagged

  • If you are viewing a page in your browser and click on the TagTeam bookmarklet, you can tell whether the page has already been tagged. If it has, then the bookmarklet form will pop up pre-populated with its current values. If it has not, the form will pop up blank.
  • If the item has already been tagged, you could exit the bookmarklet form and move on. Or you could review the form to see whether you'd like to improve upon the current tags, title, URL, or description.
    • This is the only way to change the title, URL, or description of an item already tagged, and it's one way to add new tags to an item already tagged.
    • If you add a tag, the new one will be added to the TagTeam database. If you revise a tag, your new one will be added but the original tag will remain unaltered in the database. If you delete a tag, the original will remain in the database. This is a feature, not a bug. (At least it's deliberate.) The bookmarklet assumes that all tags applied to the same item, by all users, should be merged and preserved in the database. Tags can only be deleted or converted to other tags by people with privileges granted by the hub owner.
    • To delete existing tags from an item, or to create a filter changing a deprecated tag to an approved tag whenever it appears, see the next section on modifying tags.

Viewing tagged items

TagTeam gives you many different ways to view the results of user tagging, both within TagTeam itself and through feeds available to non-users.

Viewing items tagged with a given tag

  • TagTeam will display a unique page showing all the items tagged for a given hub with a given tag. This is another way of saying that every tag library has a unique URL.
  • To view the same page without constructing the URL manually, click on any tag from inside TagTeam. In the pop-up menu there will be an option to view it ("View items tagged with TAG"), along with many other options.
  • In this view, the tagged items are listed with most recent first, just like a blog.
    • Note that the time associated with each item is the time it was tagged, not the time it was originally published. Hence, if an item was published in January 2015 but hub participants didn't notice or tag it until June 2015, then it will appear in the list with the June items.

Viewing items tagged by a given tagger

Viewing items tagged with a given tag by a given tagger

Publishing feeds for given tags and taggers

  • There many online tools for converting RSS feeds to other formats. For example, Feedburner will convert an RSS feed to an email feed. TwitterFeed will convert an RSS feed to a Twitter feed. HootSuite will convert an RSS feed to a Google+ feed. Using tools like these, you can offer your users many more choices than just HTML (the default TagTeam display format), RSS, Atom, and JSON (the built-in TagTeam options).
  • TagTeam gives you the same flexibility in publishing feeds for a given search. For details see the section on using and reusing searches below.

Modifying tags (creating tag filters)

In TagTeam, a "filter" is a rule for modifying tags. TagTeam supports three kinds of filter:

  1. An item-level filter changes a tag for one item only. If the item originally had tag A, and the filter changes A to B, then the item is then tagged with B and not A.
    • To see the filters on a particular item, click on the item to display the tag record, and then click on "Filters" in the left sidebar.
  2. A feed-level filter changes a tag for an entire input feed. If the filter changes tag A to tag B, then any instances of tag A arriving through that feed in the future will automatically be converted to tag B inside TagTeam.
    • To see the filters on a particular feed, click on the Inputs tab, then click on the particular feed, and then click on "Filters" in the left sidebar.
  3. A hub-level filter changes a tag throughout a hub. If the filter changes tag A to tag B, then any items arriving in the future, from input feeds or manual tagging through the bookmarklet, will automatically be converted to tag B inside TagTeam. In addition, all instances of tag A already in the hub will be converted to tag B.
    • To see the hub-level filters, go to any hub-level view, such as the hub front page or the Items tab for that hub. Then click on the "Filters" tab in the left sidebar.

In most tagging platforms, users can only modify their own tags. In TagTeam, the hub owner and users with permission can modify any tags in the hub. This is the power enabling a TagTeam project to manage the evolution from a folksonomy to an ontology, or from user-defined tags to a standard vocabulary of project-approved tags.

TagTeam always allows user-defined tags. Using filters, project managers can convert any tags to any other tags, but they cannot limit taggers to a predetermined set of tags or deprive them of the ability to invent new tags.

Filters can be deleted. A filter changing tag A to tag B takes effect as soon as it is created. If deleted, the instances of tag B added or created by the filter revert to instances of tag A. Permission to create filters includes permission to delete them.

Users may only create filters with the permission of the hub owner. Permission to tag is not the same as the permission to filter. To request permission, see the section on Requesting permission to tag for someone else's hub, and ask for permission to create filters, not just permission to tag. The following instructions assume that you already have permission to create filters.

Modifying tags for a single item

To modify a tag for one item only:

  • Click on the desired item.
  • When the item's summary screen appears, click the Filters tab in the left sidebar.
  • You'll then see three options:
    • Add a tag to this item
    • Remove a tag from this item
    • Modify a tag on this item
  • Click the desired option. You'll then see a dialog box where you can specify the tag to add, remove, or modify.
  • Fill in the dialog box and click Submit.

TagTeam displays a confirmation message at the top of the screen after completing the desired action.

If you use this method to change tag A to tag B, it will only change for that individual item. Other occurrences of tag A in the same hub will not be affected.

Modifying tags for all items in a feed

To modify a tags for all items in a feed:

  • From the home screen for the hub, click on the Inputs tab in the left sidebar. You'll then see a list of input feeds, or feeds from elsewhere to which this hub subscribes.
  • Click the title of the desired feed.
  • Click the Filters tab in the left sidebar.
  • You'll then see three options:
    • Add a tag to all items in this feed
    • Remove a tag from all items in this item
    • Modify a tag on all items in this feed
  • Click the desired option. You'll then see a dialog box where you can specify the tag to add, remove, or modify. * Fill in the dialog box and click Submit.

TagTeam displays a confirmation message at the top of the screen after completing the desired action.

If you use this method to change tag A to tag B for all items in the feed, then it will change all previous occurrences and all future occurrences in that feed. For example, if the feed delivers another item with tag A in the future, then TagTeam will automatically change it to tag B upon its arrival. Other occurrences of tag A in the same hub, outside this individual feed, will not be affected.

Modifying tags for all items in a hub

To modify tags for all items in a hub:

  • From the home screen for the hub, click on the Filters tab in the left sidebar. You'll then see a list of hub-wide filters already created for that hub.
  • Click the title of the desired feed.
  • Click the Filters tab in the left sidebar.
  • You'll then see three options:
    • Add a tag to all items in this hub
    • Remove a tag from all items in this hub
    • Modify a tag on all items in this hub
  • Click the desired option. You'll then see a dialog box where you can specify the tag to add, remove, or modify. * Fill in the dialog box and click Submit.

TagTeam displays a confirmation message at the top of the screen after completing the desired action.

If you use this method to change tag A to tag B for all items in the hub, then it will change all previous occurrences and all future occurrences in that hub. For example, if any item in that hub is given tag A in the future (for example, in an incoming feed or by a tagger using the bookmarklet), then TagTeam will automatically change it to tag B upon its arrival.

Subscribing to feeds from other platforms

These instructions assume that you already have permission get a given hub to subscribe to external feeds.

To subscribe to RSS or Atom feeds from other sources, including tag feeds from other tagging platforms:

  • Log in and go to the desired TagTeam hub.
  • Click the Input tab in the left sidebar.
  • On the Input tab, specify a URL for the desired feed type in the New Input Feed field.

Some tagging platforms use three distinct URLs for three distinct kinds of feed:

  1. The feed of a given tag as used by all taggers in the platform
    • For example, in Delicious: http://feeds.delicious.com/v2/rss/tag/TAG
  2. The feed of all the tags used by a given tagger
    • For example, in Delicious: http://feeds.delicious.com/v2/rss/TAGGER
  3. The feed of a given tag as used by a given tagger
    • For example, in Delicious: http://feeds.delicious.com/v2/rss/TAGGER/TAG

You decide which type of feeds are useful to your project. As long as you know the URL of the feed you want, TagTeam can subscribe to it.

Remix feeds

A TagTeam hub automatically generates or publishes three kinds of feed: one for each input feed to which it subscribes, one for each tag used in the hub, and one for each search. A remix can be any Boolean combination of any of these feeds.

You can create a remix feed by adding together its components, for example the feed from tag A and the feed from tag B. One fast way to reach this stage is to create a careful Boolean search and save the results as a remix feed. Then you can tweak the remix feed by subtracting components, such as any item with tag C or any item from a given input feed.

Viewing a remix feed

To view a remix feed:

  • From the list of all hubs in TagTeam, located the desired hub and click its title.
    • For example, locate the hub for the Open Access Tracking Project (OATP) and click its title.
  • On the left, click the Remixes tab.
    • The "Remix Feeds" screen appears.
  • On the "Remix Feeds" screen, click the name of the remix feed.

The following tabs appear on the left:

  • Items: displays items contained in the feed
  • About: contains a brief description of the feed
  • Inputs: shows the tags, searches, and items used to create this feed
  • Removals: shows the feeds, tags, and items that are removed from this feed before publication

Creating a new remix feed

These instructions assume that you already have permission to create remix feeds.

  • Log in and go to the desired TagTeam hub.
  • On the left, click the Remixes tab.
    • The Remix feeds screen appears.
  • On the Remix feeds screen, click the New Remix Feed link.
    • The "Create a new remix feed" screen appears.
  • On the New remix feed screen, supply the following:
    • Title
    • URL key
    • Description
    • Limit (how many items to show in this feed)
  • Click Create new remix feed.
  • On the left, click the Inputs tab to specify tags, searches, and items to include in the newly created remix feed.
  • Click the Removal tab to indicate items to remove from the remix feed.

Searching

TagTeam uses the Apache Lucene search engine code library, with a few modifications. For full details on its power, and the syntax it supports in search queries, see the Apache documentation itself. The instructions below outline the basics, including the points on which the TagTeam implementation departs from the unmodified Lucene search engine.

TagTeam searches cover every part of the item record, and most importantly the title of the work tagged, the description entered by the tagger, and the tags.

Keyword searching

  • To search for a keyword, just type it into the search box, with or without quotation marks.

Tag searching

  • To search for a tag, precede it with the hash symbol ("#").
    • Example: To search for read used as a tag, search for #read. The word may be used as an ordinary term in many items, but this search will only pick out items in which it is used as a tag.
  • If a hub uses a tag prefix (the way the Open Access Tracking Project hub uses "oa."), then a search for oa.read will find all items containing "oa.read". Because this string of characters is almost always used as a tag, this search will almost always amount to a tag search. However, the search will also pick up items, if any, in which it is not used as a tag. To insure that a search only picks up the tag, search for #oa.read.
  • In projects using phrases as tags, or tags containing spaces, use the rules for phrase searching below.

Phrase searching

  • To search for a phrase, simply put the phrase in quotation marks, such as alan turing.
  • To search for a tag containing a space, put the tag in quotation marks.
    • Example: If a hub uses the tag social tagging, then to search for it as a tag, search for #"social tagging" (quotation marks around the phrase, hash mark outside the quotation marks). To search for it as an ordinary phrase without the hash mark will capture all the items in which it is a tag and all the items in which it is not.

Wildcard searching

  • For a single-character wildcard search, use the question mark.
    • Example: To search for "test" or "text", search for te?t.
  • For a multi-character wildcard search, use the asterisk.
    • Example: To search for "testing" or "tester", use test*.

You cannot use "?" or "*" as the first character of a wildcard search.

Fuzzy searching

  • To do a fuzzy search, use the tilde symbol.
    • Example: If you search for roam~, TagTeam finds terms such as "foam" and "roams".

Boolean searching

  • TagTeam supports full Boolean searching.
    • For conjunction, use the operator "AND" or "+".
    • For disjunction, the operator "OR" or "||".
    • For negation, use the operator "NOT" or "-".
    • If you use the operator words rather than the operator symbols, they must be in all capital letters.
  • In TagTeam, the default Boolean operator is conjunction. Hence if two keywords appear without an explicit operator between them, such as A B, TagTeam will search for A AND B.
    • Note that the standard Lucene search engine makes disjunction the default instead.
  • You can use parentheses to mark the components of larger Boolean compounds.
    • Example: A search for (tagging OR bookmarking) AND crowd will find all items containing the keyword "crowd" and either the keyword "tagging" or the keyword "bookmarking".
  • You can mix keywords and tags in the same Boolean search.
    • Example: A search for write AND #read will pick up all the items containing the word "write" and the tag "read".
  • You can combine Boolean operators with phrase, wildcard, or fuzzy searching.

Searching for tagless records

  • To search for hub items containing no tags, search for NOT #*.
    • In projects where every item should be tagged, this search will display the items remaining to be tagged.

Using and reusing searches

  • Every search in TagTeam has a unique URL for bookmarking, linking, and sharing.
    • Run the search. When the results come up, click on the link labelled "Permalink" next to the search box. This version of the URL is slightly cleaner than the URL displayed in the browser, although that URL would also work.
      • Sometimes these URLs will use the escape characters %28 and %29 for "(" and ")" respectively. We'll fix this soon. Meantime, you can replace the escape characters with the parentheses to make the URL easier to type and decipher.
    • The syntax is so predictable that you could construct the URL without running the search.
  • Every search in TagTeam can also become a component in a remix feed.
    • Run the search. When the results come up, click on the link labelled "Add to a remixed feed" next to the search box.
      • If you don't already have any remix feeds in that hub, this command will create one, using this search as the first component.
      • If you have exactly one or more remix feeds in the hub, this command will pop up a menu asking you whether to add the search to one of the existing feeds or start a new one.
    • Because every remix feed can be published in RSS, Atom, or JSONP, then every search can be published as an RSS, Atom, or JSONP feed.
    • For more details, see the section on remix feeds above.
  • TagTeam gives you the same power to create a unique URL for the collection of all items tagged with a given tag, all items tagged by a given tagger, and all items tagged with a given tag by a given tagger. For details see the section on viewing tagged items above.

Cross-hub searches

  • So far, the TagTeam search engine only searches one hub at a time. If you're in a given hub, the search engine will search just that hub. To search a different hub, exit the original hub and enter the hub you want to search.
  • However, Google indexes TagTeam records, and you can use Google for cross-hub searches. Simply use this syntax in the Google search box: site:tagteam.harvard.edu SEARCHSTRING.
    • If you use our open code to launch your own instance of TagTeam, then just replace "tagteam.harvard.edu" with the domain of your own instance.

Copyright and licensing

  1. The Harvard copyright statement only covers the TagTeam code, not the TagTeam content or data.
  2. Moreover, Harvard has chosen to make the code free and open source. The code is at GitHub under an Affero General Public License (AGPL).
  3. When users enter original content into TagTeam, they retain ownership of it. But as a condition of using the software, they grant TagTeam a license to use it. See the details in Section 6.3 of the terms of service.
  4. When users enter content they don't own, they warrant that they have the rights necessary to share it through TagTeam. See the details in Section 6.4 of the terms of service.
  5. Some data arise from the use of TagTeam, such as the dates when items are tagged. Insofar as these data are copyrightable by TagTeam, TagTeam relinquishes its copyright and releases the data into the public domain through a CC0 Public Domain Dedication. Insofar as these data are copyrightable by users, users also agree, as a condition of using the software, to release the data into the public domain. See the details in Section 6.6 of the terms of service.
  6. These terms of service apply only to the Harvard instance of TagTeam. The code is open, and users are free to create their own instances. We encourage those who do so to draft their own terms of service to govern their own instances of the software. See Section 1.2 of the Harvard terms of service.