#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass article
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title

LON-CAPA Developer's Manual
\layout Author

(source material)
\layout Section

About This Document
\layout Standard

The purpose of this document is to introduce developers people to LON-CAPA,
 and enable them to start doing real work with the system as quickly as
 possible.
 This should prove useful both to people who already intend to develop with
 LON-CAPA, and to technical people who are evaluating LON-CAPA to see if
 it suits their needs.
 
\layout Standard

The most daunting task facing new developers is understanding how the whole
 system fits together; individual pieces are usually sensible but like any
 large program it is difficult to understand the forest by looking at just
 the trees.
 Therefore, this document will start out with the highest-level overview
 of the system, which can be safely skipped if you already know what LON-CAPA
 is.
 
\layout Standard

Next, we'll look at the major subsystems of LON-CAPA and how they fit together
 at a high level, with enough detail to understand the context a given piece
 of the system functions in.
 Appropriate pointers will be given to the detailed documentation on the
 various subsystems, so this section can 
\layout Standard

Then a brief tutorial in adding a 
\begin_inset Quotes eld
\end_inset 

handler
\begin_inset Quotes erd
\end_inset 

 to LON-CAPA will be given, enabling you both to understand how to add brand-new
 functionality to LON-CAPA, and better understand the majority of the code
 in the system which is in the form of handlers.
\layout Standard

Finally, the last and largest portion of this document will be extremely
 detailed examinations of the subsystems from a technical point of view,
 including API descriptions suitable for use in programming.
 Obviously you will not need to read this over entirely, unless you really
 want to know what the system can do.
\layout Section

What is LON-CAPA?
\layout Standard

The 
\series bold 
L
\series default 
earning
\series bold 
O
\series default 
nline 
\series bold 
N
\series default 
etwork with a 
\series bold 
C
\series default 
omputer 
\series bold 
A
\series default 
ssisted 
\series bold 
P
\series default 
ersonalized 
\series bold 
A
\series default 
pproach (LON-CAPA) is an integrated system for online learning and assessment.
 It consists of a learning content authoring and management system allowing
 new and existing content to be used flexibly, a course management system,
 an individualized homework and automatic grading system, data collection
 and data mining system, and a content delivery system that will provide
 gateways to and from NSF's National STEM Digital Library.
\layout Standard

In particular:
\layout Itemize

The LON-CAPA software provides instructors with a common, scalable platform
 to assist in all aspects of teaching a course, from lecture preparation
 to administration of homework assignments and exams.
 It allows instructors to create educational materials and to share such
 learning resources with colleagues across institutions in a simple and
 efficient manner.
 
\layout Itemize

It provides an extremely sophisticated assignment engine that can create
 unique homework assignments and examinations for each student in a class.
 Its formative and summative assessment tools grade a broad variety of objective
 problems and assist in evaluation of essays.
 
\layout Itemize

It provides prompt feedback for students and instructors, as well as statistical
 information on performance and on effectiveness of materials.
 Discussion pages attached to every homework assignment encourage communication
 among students and faculty.
\layout Standard

The LON-CAPA software is freely available and free (GNU General Public License),
 and may be modified and adapted.
\layout Standard

LON-CAPA is being developed and implemented by an enthusiastic group of
 faculty and professionals who recognize that Information Technology can
 play an important role in improving students' learning and understanding.
 Current members of the project include faculty from universities, colleges,
 and K-12 schools in the US, Canada, Asia, Africa, and Europe.
 The core development group is located at Michigan State University.
\layout Subsection

Why LON-CAPA?
\layout Standard

There are tens of learning management systems to choose from.
 Why should you choose LON-CAPA over the competition?
\layout Itemize


\series bold 
Unparalleled assessment engine
\series default 
: The assessment engine in LON-CAPA is the beneficiary of over a decade
 of development and refinement.
 Few projects are even in the same league of the LON-CAPA project in experience
 with sophisticated homework problems.
 Sophisticated randomization features go well beyond merely randomizing
 the order of multiple choice problems; everything can be randomized, from
 the exact parameters in a given numerical problem to 
\emph on 
which
\emph default 
 parameters are missing for a given student.
 See our Author's Manual for an idea of how powerful the assessment engine
 is (http://msu.loncapa.org/adm/help/author.manual.pdf), or try our Demo Course
 (http://demo.lon-capa.org/cgi-bin/signon.pl).
\layout Itemize


\series bold 
Full course support
\series default 
: LON-CAPA is capable of running your entire course from top to bottom.
 LON-CAPA can host all of the content of the course, from syllabuses to
 actual course materials.
 It can track your students grades, with as much power as you need.
 Want to give students bonuses for getting a problem right on the first
 try? Or insert external grades into the system from an external data source?
 Powerful communication features enable discussion between the instructors
 and students, or among the students themselves.
 From the initial course creation to the final grades readout, LON-CAPA
 has all the power you need to run courses.
\layout Itemize


\series bold 
It's free
\series default 
: The thousands or millions you save over expensive course management solutions
 can be better spent on computers, or directly spent on your students.
 LON-CAPA can frequently do more with less then some of the largest commercial
 competitors, too.
\layout Itemize


\series bold 
It's free
\series default 
: As in liberty.
 No need to buy an extra-special license just to have the privilege of developin
g extensions to the system.
 You have full access to the entire system.
 You aren't restricted to carefully delimited parts of the system the vendor
 deems 
\begin_inset Quotes eld
\end_inset 

safe
\begin_inset Quotes erd
\end_inset 

 for you to access.
 You also have full access to all the data on the system; LON-CAPA never
 locks up your data.
 There aren't any hidden secrets in the system, either, when you're free
 to scrutinize all of the source code.
 And it won't become closed later either, thanks to the licensing.
\layout Itemize


\series bold 
Large Digital Library
\series default 
: LON-CAPA's digital library means you have access to thousands of high-quality
 learning resources right off the bat, without writing them yourself.
\layout Itemize


\series bold 
Power for the Users
\series default 
: LON-CAPA's grants a lot of power to the instructors to control their course;
 the system imposes minimal arbitrary restrictions on the instructors because
 the design is mature.
 To get an idea of what the instructors can do, see our Course Management
 Manual (http://msu.loncapa.org/adm/help/course.manual.pdf).
\layout Itemize


\series bold 
Improve Student's Performance
\series default 
: Several studies have repeatedly shown that using LON-CAPA can significantly
 improve student performance.
 One especially interesting result has been its ability to nearly eliminate
 the gender gap in technical subjects such as physics, where men have traditiona
lly outperformed women.
 
\layout Comment

I'd 
\series bold 
like
\series default 
 to say here that multiple choice systems have been demonstrated to do the
 opposite; can we back that up? Links to actual papers would be great, on
 both sides.
\layout Subsection

Features
\layout Standard

TBD
\layout Subsection

Philosophy and Pedagogy
\layout Standard

TBD
\layout Comment

I'd 
\series bold 
really
\series default 
 like to have a lot of what I've heard written down.
 So much cool stuff has been said but I don't know where I can find it.
\layout Subsection

Conclusion
\layout Standard

We hope by now you're as excited as we are about the system.
 LON-CAPA is really powerful and good for both students and instructors,
 and you can't beat the bang-for-the-buck.
\layout Standard

Now you know what LON-CAPA is all about, let's start looking at the internals
 to see how we do all this great stuff.
\layout Section

LON-CAPA Technical Overview
\layout Standard

In a nutshell, LON-CAPA is all about bringing learning 
\series bold 
resources
\series default 
 and 
\series bold 
people
\series default 
 together with 
\series bold 
technology
\series default 
.
 Thus, the best way to understand the system is to understand how it models
 learning resources, how it understand people, and last (and really, least
 importantly) what technology supports it.
\layout Subsection

Learning Resources And Assembly
\layout Standard

see Guts_Authoring.tex
\layout Subsection

Network
\layout Standard

sharing
\layout Standard

dynamic replication
\layout Standard

notification
\layout Standard

show replication sequence
\layout Subsection

Courses
\layout Standard

The end result of all of this assembly is an actual course that students
 can participate in.
\layout Standard

Courses are themselves sequences that tell the system what the course consists
 of.
 Course instructors or administrators can manipulate this sequence through
 the use of the Course Documents screen; see the Course Documents Screen
 chapter in the Course Management Manual (http://msu.loncapa.org/adm/help/course.ma
nual.pdf) for more detailed information about that.
 
\layout Standard


\series bold 
INSERT OVERVIEW/Initialization Of Course from lonuserstate.pm here; make
 sure to mention lonnavmaps and the 
\begin_inset Quotes eld
\end_inset 

compiled course hash
\begin_inset Quotes erd
\end_inset 

 here.
\layout Subsection

Cascading Parameters
\layout Standard

Parameters cascade and can affect anything in the course.
 Extensions should take advantage of parameters if it at all makes sense.
 Makes common operations easy.
 Very powerful; 
\begin_inset Quotes eld
\end_inset 

simple problem
\begin_inset Quotes erd
\end_inset 

 is actually implemented in terms of parameters.
 
\layout Standard

Most common parameters can usually be accessed through lonnavmaps, which
 provides a relatively nice interface to resources and their parameters.
 See navmaps.
\layout Subsection

Finding Resources
\layout Standard

search 
\layout Standard

browse
\layout Subsection

Permissions
\layout Standard

sharing, restrictions, licenses (should put where this is done)
\layout Subsection

Affect On System (rename)
\layout Standard

Supporting highly dynamic, geographically distributed, configurable resources
 drives much of the system.
 Understanding this 
\layout Standard

Practical effects on how you need to think about the system:
\layout Itemize

Don't assume resources are on the hard drive.
 You need to ask the system to first replicate the resources as necessary.
 
\layout Itemize

Make sure you use the rich environment, don't try to fight it, or reinvent
 the wheel.
 See the discussion on the Environment in the Technology section.
\the_end