EDGE: Engineering Design Guide and Environment
/public/Help/

EDGE Mission

Table of Contents

This node describes why and how the EDGE system operates the way that it does.

Web Interface

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.

Accessibility

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.

Stability

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.

Extensibility

All functionality not provided by the core is provided by superproject scripts. These scripts should compose the bulk of the user interface activities.

File Repository

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:

Information
Knowledge associated with a project
Data
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.

Consequences

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.

Version Control

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:

Consequences

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.

Editor Perspective

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:

  1. 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.
  2. 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.
  3. 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.

Managerial Perspective

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 issues

Many 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.

Technological issues


EDGE Home | EDGE Help | EDGE Mission | EDGE Development