Table of Contents
This node describes why and how the EDGE system operates the way that it does.
The web-site interface to the system is how members and non-members of projects publish and retrieve information about all projects in the system.
The following are the general tasks of the web interface.
Simple Project Publishing
It should be simple for an inexperienced student group to publish their ideas and materials in a way that allows them to be simply edited by all members of the project and viewed by outsiders through a consistent and pleasing interface.
The material-to-be-published should be viewable by appropriate individuals associated with the project. The material should not be viewable by outsiders until and a project curator has verified and authorized the release of the material.
Generic Web Access
A user of the system should be able to access all system features using a generic web browser without requiring any dynamic page management on the part of the user's browser.
All content should be a part of a project, with appropriate access given to those users who have a need to update the content. The generic site interface should be only as complicated as necessary to manage projects. The projects themselves are the focus of the site activities.
All stateful information should be available to be bookmarked by the user for easy immediate access to the same information in a later session.
All pages with multiple actions should generate a list of actions to be displayed in the content footer of the page. This gives users a standard location to look when they desire to perform actions on node data. This interface should be common to all project scripts as well.
Any page with dynamic content should clearly state, in the content footer, the time of last update. This allows users of the page to know how up-to-date the display information is.
The web interface should not rely on a user having a particular web browser or even a browser with a graphical interface.
Hindering accessibility to either readers or editors will result in hindering of the general flow of information and contribute to apathy of both parties toward the system in general.
The core functionality should be as minimal as possible to allow the various nodes and scripts to be executed and displayed. The run-time CGI core exists outside of any repository, although it likely will be an export from within a repository.
All functionality not provided by the core is provided by superproject scripts. These scripts should compose the bulk of the user interface activities.
The file repository is the centerpiece of agile project management. It gives a common place for all editing members of a project to put their knowledge of the project, and all viewing members of a project to retrieve this information at the user's convenience.
In order to appreciate the benefit of a project's file repository, it is important to keep in mind the following definitions:
- Knowledge associated with a project
- Some particular representation of knowledge
Data can certainly be generated from information, but not necessarily information from data.
Centralization of Information
A single repository with access shared by members of that project prevents unnecessary duplication of information but allows arbitrary duplication of data. This centralized information source can be easily maintained and backed-up for reliability.
A common information repository results in less need for face-to-face meetings to propagate important information between project members, which means that less time is wasted in organizing meetings. This is not to say that meetings shouldn't take place, but that they needn't occur every time someone associated with a project needs information about or from the project.
When information is distributed among members of a project, it is likely that some amount of duplication will occur. Without a centralized repository, this duplication can lead to inconsistencies between the copies and cause a general decay on the reliability of the duplicated information. A centralized repository allows all project members to agree on what is the 'accepted' version of a particular set of information.
A repository under version control means that any time the repository is altered, the previous state of the project is not destroyed, but kept in an archive. Any change to the repository is also accompanied by metadata consisting of:
- Author name
- Log message
With version control on a repository, the complete history of the project can be maintained and viewed by any member of the project. It is impossible for information in the repository to be lost; any information that was ever in the repository is always available for retrieval.
To fully exploit this effect, any an all information associated with the project should be within the repository. If a particular piece of information is not necessary the worst that can happen is some wasted disk space, but if that information is omitted and later required nothing can be done; if it wasn't in the repository it can't be tracked.
EDGE's Unique Combination
The uniqueness of the EDGE system is in it's combining a project's information-storing and versioning repository with a simple-to-edit wiki interface. This presents many benefits and challenges to the users and developers of such a system.
Casual Observer Perspective
Simply having a wiki-like user interface provides the most immediately noticeable feature of all pages having an identical look-and-feel. A consistent user interface allows a casual reader to quickly become familiar with at least the navigation and style of all documents, if not the content layout within the documents themselves.
Noting the last edit time of any particular node allows the user to easily recognize information that may be out-of-date, and to inform the project editors of such information.
For the editor of a project, it is important that the interface be as standard as possible so that all of the system's responses to their actions are predictable.
The Subversion interface provides simple bulk access to the repository data, both private and public, while the web file interface mirrors the Subversion access methods and nomenclature. Having multiple methods of interacting with the repository allows simple file addition and modification from any public internet terminal, while also allowing bulk modification through a user's on working copy of the repository.
The wiki renderer uses a de facto markup standard to allow a bulk of ready-made content to be used as reference material. The creation and modification of this content by a web interface provides a convenience to the editor that they can make changes to any wiki document from any internet terminal. The editors can also modify their wiki documents through their working copy, allowing changes across multiple documents to be made simultaneously.
In addition, the wiki allows the editors to guarantee a certain level of consistency in how their work is presented to the world. They can be certain that the readers are presented with information in a way that is easily interpreted (as much as a technological solution can).
Drawbacks to pulling wiki nodes out of the repository are:
- The Subversion MIME type of the file must have a
particular value in order for the web interface to
discriminate these documents from other files.
- This only affects editors when creating new nodes; once a node is created with the correct MIME type, it will retain the type while it is modified.
- Speed of file extraction is slower than from a
similarly-functioning purpose-built database.
- This means that more dynamic abilities (such as templating) of a wiki format are sacrificed for reasonable speed.
- Changes made outside of the CGI environment are
difficult to incorporate into the web interface.
- The current link index is unaware of changes made to wiki documents outside of the web editor.
A major benefit of the combined SVN/wiki system is the ease and flexibility with which communication can occur between project "workers" and "managers".
The versioning system gives managers a deeper insight into the organization and flow of a project without hindering the activities of the workers. The manager can see everything about a project that is versioned, and have the ability to demand more transparency into the activities of the workers.
The wiki in turn allows the workers to communicate amongst themselves and the managers in a simple, verifiable, and accountable way.
Issues in Current Implementation
The current incarnation of these ideas is far from perfect. The issues seen with the current implementation can be separated into social and technological areas.
Social issuesMany users are unfamiliar with concepts of version control or semantic markup. There is a certain minimum learning curve associated with effectively using the EDGE system; this applies to editors as well as managers.
- Multiple access methods to wiki nodes present unique challenges to maintaining the consistency of the repository/document-database
- Forcing the wiki into a file repository create new
issues with document naming, such as
- Directory separators in node names cause real directories to be created in the repository, which may or may not be the wish of the editor
- Certain characters are legal in Subversion and most UNIX file systems that are illegal in FAT/NTFS file systems (this includes case sensitivity issues)