Index: openacs-4/packages/dotlrndoc/www/doc/nomenclature.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrndoc/www/doc/nomenclature.adp,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/dotlrndoc/www/doc/nomenclature.adp 14 Oct 2001 21:42:58 -0000 1.1
+++ openacs-4/packages/dotlrndoc/www/doc/nomenclature.adp 29 Mar 2002 17:21:56 -0000 1.2
@@ -1,59 +1,287 @@
<%= [dotlrn_header "dotLRN Nomenclature"] %>
-dotLRN Nomenclature
-by Ben Adida, part of dotLRN Documentation.
+dotLRN Nomenclature: a dotLRN Primer
+by Ben Adida, part of dotLRN Documentation. (last updated: 28 February 2002)
-dotLRN is a Course Management System which means it
-helps manage courses, but does not perform the actual instruction of
-the courses. This document defines the nomenclature
-in the dotLRN project, because the components of a Course
-Management System are named very differently by various teaching
-institutions. In particular, since dotLRN is being developed for MIT
-Sloan, an attempt is made to cleanly work within existing MIT
-terminology while being generic enough to use by all.
+dotLRN is a Learning Community Management System
+which means it helps manage communities of users and the exchange of
+information therein. This document defines the
+nomenclature in the dotLRN project, with specific
+examples of how this nomenclature can be used in the context of
+dotLRN's primary use: that of a Course Management System.
+
1. dotLRN Communities
+The core concept within dotLRN is the dotLRN User Community.
-Class
+Community
-A class is a topic being offered by the
-institution. An example is "Introduction to Micro-Economics". Some
-institutions use the term "course", but this conflicts with MIT's
-reference to entire departments (Course 15). A class is thus a single
-topic that spans across years and does not specify a single offering
-of that topic.
+A community is a group of users that work together and exchange
+various types of information. There may be different types of
+communities, but all have basic properties, such as a community name
+and community ID.
-Class Instance
+
-A class instance is a particular offering of a
-class. An example is "Introduction to Micro-Economics - Spring 2002,
-Section A". A class instance thus has a very well-defined student
-list, professor, and TAs. It has specific material relevant to that
-offering of the class, a schedule, news events, etc...
+
Class
-Student
+A class is a topic of instruction, such as "Finance 101." A
+class is not a community (this will become clearer
+soon).
-A student is an individual who is registered for a particular class
-instance.
+
+
Class Instances and Clubs
-Instructor
+Two basic types of communities implemented in core dotLRN are
+Class Instances and Clubs. Class Instances are
+for structured groups of students, while Clubs are for unstructured
+student activities. A Class Instance, as its name indicates, is a
+specific instance of a Class. "Finance 101 - Spring 2002" is an
+instance of "Finance 101." It doesn't make sense for "Finance 101,"
+the topic of instruction, to be itself a community, since Finance 101
+Fall 2000 and Finance 101 Spring 2005 will probably have nothing to do
+with on another apart from teaching approximately the same material.
-An instructor is one who teaches a particular class instance. An
-instructor could be a professor in title or not. The term instructor
-allows the system to be more flexible to different teaching
-environments.
+
-
TA
+Open, Wait, Closed Communities
-A TA (Teaching Assistant) is one who assists the instructor in the
-teaching of the class instance.
+Communities can have one of three Join Policies. A join policy
+defines the process by which a dotLRN User can become a member of the
+community. For now, we will consider only dotLRN Full Access
+Users (see below for more information on other types of dotLRN
+users).
-Administrator
+
-An administrator is one who assist in managing issues surrounding a
-class instance, but doesn't play a role in the teaching process.
+A community with open join policy is visible in read-only
+state to non-members. Any full-access user can join the community at
+will, without the intervention of any other user.
-
+
+A community with wait join policy is visible in read-only state
+to non-members. A full-access user can apply to join the
+community. The application must be approved by an administrator of the
+community.
+
+
+
+A communty with closed join policy is not visible to
+non-members. Users become members only when explicitly added by the
+community administrator.
+
+
+
+
in MIT SloanSpace: Class Instances and Communities
+
+In MIT SloanSpace, dotLRN Communities are referred to as SloanSpace
+Groups, while dotLRN Clubs are referred to as SloanSpace
+Communities.
+
+
+
+The reason for this potential nomenclature confusion is historical:
+SloanSpace v1.0 used a certain terminology. It would be unacceptable
+to change it for SloanSpace v2.0. Similarly, it would be unacceptable
+to stick to the SloanSpace nomenclature and impose it to all users of
+dotLRN.
+
+
+
+Thus, dotLRN nomenclature, although internally self-consistent, is
+entirely configurable by the user using global parameters.
+
+
2. dotLRN Users
+
+A dotLRN User is an individual with an email address username and a
+password to the dotLRN system. Each user is uniquely identified by
+email address.
+
+Access Level: Limited or Full
+
+dotLRN users can have either Limited Access or Full
+Access.
+
+
+
+A limited-access user is one who has access only to class instances
+and communities she is registered for and has no ability to
+browse any other section of the dotLRN application. This applies even
+to open communities: if a limited-access user is not a member of a
+given open community, she will not be able to browse any page that may
+enable her to become a member.
+
+
+
+A full-access user is one who has access to all browsing
+sections of the dotLRN application. A full-access user can surf around
+and register for open communities, apply to be accepted into wait
+communities, etc... A full-access user also has the ability to store
+user-specific information, like personal files and personal calendar events.
+
+
+
+
Access to Private Information
+
+Certain users of the system may be dotLRN Guests, meaning that
+they do not belong to the parent organization that runs the dotLRN
+instance. These guests may participate in the community as
+full-fledged members but, for certain legal or privacy reasons, may
+not be allowed to view other users' private information.
+
+Any dotLRN user can be a guest or a non-guest. Full-access members can
+be guests. The only difference between a guest and non-guest is
+whether private user information (email address, address, phone #,
+etc...) can be read by these guests.
+
+System-Wide Roles
+
+dotLRN users have system-wide profile information. For example, in the
+context of a Course Management System like MIT SloanSpace, they may be
+Professors, Students, or Administrative Staff.
+These system-wide roles define the user's specific profile in the
+system as a whole, without regards to community-specific roles.
+
+
+
+
Community-Specific Roles
+
+dotLRN users have specific roles within the communities they belong
+to. These roles are classified in two main categories: dotLRN
+Community Members and dotLRN Community Admins.
+
+
+
+dotLRN Community Members of a given community have normal
+read/write access to a community. They cannot perform administrative
+functions, like create a new forum, add group calendar events, create
+a new survey, etc... However, they can contribute to existing
+discussion forums, view calendar events, and respond to surveys.
+
+
+
+dotLRN Community Admins have all the privileges of normal
+community members plus complete administrative rights over all
+components of the community. dotLRN Community Admins completely
+control a community: they need no further help from any other users to
+add data, applications, or users to their workspace.
+
+
+
3. dotLRN Applets
+
+A dotLRN community is mostly a container of users and applets. A
+dotLRN Applet (nothing to do with a Java applet) is a small
+application that can be added to the community to enable new
+functionality.
+
+
+
+Examples of existing applets include: Discussion Forums, Surveys,
+FAQs, News, Calendaring. These applets are scoped in order to
+correctly segment communities from one another. Data that belongs to
+one community is not viewable by another: it is as if it doesn't exist
+unless you are in the appropriate community.
+
+
+
+Certain applets are community-centric in that they offer
+functionality that makes sense only in the context of a given
+community. Discussion Forums is one solid example of this: a
+discussion forum must pertain to a given community.
+
+
+
+Other applets are user-centric in that they also manage data
+that is user-related, not linked to any given community. Calendaring
+is one such applet: although there are community events, there are
+also personal events.
+
+
+
+
4. Portals
+
+The entire dotLRN architecture is based on the New Portal
+Architecture. The design and specifics of this architecture are
+described in another document, but the basic terminology and concepts
+are as follows.
+
+
+
+
Portal Page
+
+A Portal Page is a single page display of portal boxes. A
+portal page has a Portal Layout that defines how the boxes are
+arranged on the page. Common layout schemes include 2-column,
+3-column, 3-column-with-header. New portal layouts can be implemented
+at will.
+
+
+
+A portal page can be configured so that the portal boxes can be moved
+around the page by someone with appropriate permissions.
+
+
Portal
+
+A Portal is a set of portal pages that are tied together so
+that a browser may navigate easily between the various portal
+pages. This is particularly useful when portal boxes need to be
+organized by functionality theme.
+
+Portlet or Portal Datasource
+
+A Portlet or Portal Datasource is a set of functionality
+that is presented in the form of a portal box. A bboard portlet, for
+example, is functionality that displays discussion forums inside a
+portal box.
+
+Portal Element
+
+A Portal Element is a single box on a given portal page. A box
+that display discussion forum information on Jane Doe's personal
+portal page #2 is one portal element that corresponds to
+the instantiation of portlet within a portal page.
+
+
+
+A portal element can be moved, shaded, or hidden altogether, given the
+appropriate permissions. It can be moved to a different page of the
+same portal. While a portlet can be instantiated multiple times within
+a given portal, a portal element is unique per portal as it represents
+a single instance of the portlet: thus, a portal element can appear on
+only one page of the portal in one location. To appear in more than
+one place, a new instance of the portlet would have to be instantiated.
+
+
Portal Themes
+
+A portal page can be rendered in a given Portal Theme that
+determines the look-and-feel of each box. The layout is NOT
+determined here, only the specific look-and-feel of portal element
+borders, buttons, and internals.
+
+Portlet Parameters; Portal Element Parameter Values
+
+For each portlet, there is a set of Portlet Parameters. For
+example, the calendar portlet has a calendar_view parameter
+that indicates whether the portlet should display data in the form of
+a list, day-, week-, or month- view.
+
+
+
+Each Portal Element has Portal Element Parameter Values for
+each parameter of the portlet it instantiates. For example, the
+calendar portal element on Jane Doe's personal portal may have a value
+of "day" for the calendar_view parameter.
+
+
+
+
Portal Template
+
+A portal template is much like any other portal, except that it is
+used as a template for creating other portals.
+
<%= [dotlrn_footer] %>
+
+