Help Documentation on Documents


CASCADE has been designed as an intuitive collaborative authoring tool.

To get started, a few words about how CASCADE works are probably in order. CASCADE is a client server tool. It only works when you are connected to the Internet. It doesn't matter whether the connection is permanent -- a LAN and an IP address, or temporary -- through an Internet Service Provider(ISP). A separate section provides information on how to install CASCADE and how to start CASCADE.

To allow for collaboration, CASCADE works by moving documents back and forth over the network. This can cause a little delay from time to time. While CASCADE is designed to be network efficient, if you are using a modem or working on a congested network, some transactions may be a little slow. For many actions you will take, there will be several transactions between your machine and the server at the University of Pittsburgh. The server will be checking a number of things before taking action and it is doing this to insure that you and the others working on the project will collaborate without interference.

In collaborative efforts, most users spend the majority of their time reading and reviewing documents. This fact, coupled with the fact that document editing requires "locking of documents", has led to CASCADE having two "modes" or "states of operation". One mode of operation is Edit and the other is Read/Comment.
Edit mode is signified in three ways:

Read/Comment mode is signified in three ways:

Under CASCADE, different users are given different rights to documents. Assuming you have been granted the right, any document that you are reading can also be edited and updated. Finally, some people will want to create new documents or import documents created on their local machines into CASCADE. The following section describes how to do these tasks:

Finding a document

Before you do anything else, you need to be able to find a document. CASCADE keeps documents in folders and folders may be contained in other folders. For each project, there is a root folder -- a starting point. When you enter CASCADE you are at the root folder. To go to a subfolder, simply click on the folder name that appears in the document/folder window on the left side of the mainscreen. When working in the document/folder window, only use a single click of the left mouse button, and not others (middle or right button). For Unix/Xwindows users a single click on the middle button will bring up a document information window for the document. Windows 95 users can show document information by right-click the mouse button. When you get to the folder that contains the document you wish to read single click on the document and it will be displayed in the Document viewer. In a given folder, subfolders will be listed first, followed by documents.

There are different kinds of folders and documents in CASCADE and they are displayed by using different colors and icons. Should you want to know more about the folder and document color coding, you can observe the CASCADE File Types in the Preferences dialog which is found by going to the Main menu, Preferences dialog window and File Type tab.

You may also access documents by using the "Browser". The browser may be accessed via the Navigation menu where you will see that its graphical tree-like structure makes it easy to look at large collections of documents and folders.

Making a comment

CASCADE makes it easy to make comments. CASCADE also helps you learn about comments that others have made. Whenever a user makes a comment or edits a document, all other project members may learn about other users activity through the "Project Activity" feature which is found in the Information menu on the CASCADE menu bar. For now we will focus our attention on how to make a comment.

When you want to make a comment in a document:

A comment dialog window will open. Type in your comment and click the Accept button. CASCADE will take care of all the details and return you to the document that you were reading. Clicking the Cancel button will abort the comment process.

To help you communicate with the others working on the document, CASCADE provides a way for you to classify the comment you have made. For most projects, the classification will be in terms of the status (open, closed, etc...), disposition (project, group, author, etc...) and type (question, objection, etc...). You may accept the default classification that is provided by the system or change the classification by using the pull down combo boxes.

Once you have made a comment, it will appear at the point where you have made the comment in the document as a colored box with your name in it. The color of the box will be an indicator of one of the classification choices. For example, by default, comments are shown with colors that represent the type of comment while "questions" show up as a white box and objections show up as red boxes. You can change which comment classification is used to color the boxes by chosing the Comment Display option in the Navigation menu.

Thus, the names on colored backgrounds that appear in the document are active links to comments that others have made. The label tells you either the name of the person who made the comment, or the date/time the comment was made, or some other label depending on the setting, and the color tells you about the classification of the comment. To see a comment, click the LEFT mouse button on the colored label within the document. A "Comment Review" window will open.

Editing a document

To edit a document that you are reading, simply select "Edit Document" from the Document menu on the main menu bar. You will notice that after you select Edit Document the screen will change from light blue to white, the cursor will change from a "link arrow" to an I bar, and the filename panel at the bottom left of the screen will say "Edit Mode". When you have finished editing you may choose "Save and Continue Editing" from the Document menu to save the file and continue your editing or you may choose "Save and Exit Editor" to save the file and return to Read/Comment mode.

Of course there are other options under the Document menu. If you are doing a lot of editing, it is probably a good idea to periodically save your work. This is really important with client server applications because it is possible that you could lose the connection to the server for reasons which you have no control. You can choose the "Discard Changes" option to remove any changes you have made to the document while continuing to edit it or you may select "Discard Changes and Exit Editor" to leave the document without saving any changes and exit editing mode.

Creating a new document

Creating a new document in CASCADE is simple. First, make sure that you have moved to the folder where you want to create the new document. From the Main menu on the menu bar, chose the option Create New Document. For now we will assume all of the information is correct -- you are the author, you are creating a type = CASCADE, subtype = document, the parent ID is correct and sibling order is greyed out. For now we will ignore the access codes and the groups, which we will assume to be correct. This leaves only the document Description which is just above the light grey separator line to be entered. Type the name for your new document in the Description box. Your new document name should be decsriptive and concise -- generally 25 characters is about the maximum that can be placed on a button and can be read when the CASCADE display is at a normal size.

After you have filled in the document description, simply click on the OK button. This will close the dialog window and open the new document in edit mode. Type as little or as much as you want. You may also create empty documents to be filled in later if you wish. Next, save the document as you would save any editing. That's it. Once again to create a document:

Access Protection

CASCADE is designed so that ultimately it will work with many different document types. The type and subtype combo boxes let you specify the type of document to create. At this time, the system only accepts a couple of the basic types. The sibling order listbox is designed to allow you to position a document within an "ordered folder". For now, we will assume you will be working only with "unordered folders", which means this option will be greyed out.

Finally we turn our attention to the matter of "access protections". CASCADE has a very sophisticated notion of document protection. Generally, you will simply accept the defaults -- which are "inherited" however, you may change them as you wish. Here's how the document protection works. Every document has a five digit protection code. This code is set by using the check boxes at the bottom of the document creation dialog. We will ignore the "Project" option for now and focus on the other digits. The default access protection is Executive = 5, Edit = 4, Add = 3, Comment = 2, and Read = 1. This means that only project members with an access right of 2 or higher can comment on a document. Users need an access right of 4 to edit a document, etc. If you change the protection of a document to 55555, only people with an access right of 5 can read the document. Ok so far, but it really is more sophisticated. Notice that below the protection section is a list of the groups in the project. You can indicate which groups will be allowed access to the document. Thus, if only one group is allowed access, then only the people that belong to that group will be allowed to work with the document, and then they will only be allowed to do the things authorized by the groups access priviledge. Thus, imagine there is a group called "alpha" with an access right of 2. Also imagine that alpha is allowed access to a document protected 54221. This would say, anyone in alpha can add to, comment on, or read the document. If at some point the author -- who is always assumed to have an access right of 5 changed the document protection to 55551, then the alpha group would still be allowed to read, but they could not comment, add to, or edit the document.

One final note. Remember the "Project" check box. It is used to say that the checked feature, let's say "reading", is open to anyone in the project, and is not restricted by group. This option can be used to eliminate group restrictions should the author choose to do so.

Importing a document

In order to import a document, it must first exist as a file on your local machine. As with internal documents, CASCADE is designed to work with many different document types. You can import many document types (See File Types), but keep in mind that the only file types which you can edit and save using CASCADE are plain text (ASCII) and CASCADE file types. For other file types, you will need to edit the document using the appropriate application for that file type and then re-import the document into the project space.

Here is a summary of how to import a document. You will take the same steps as for creating a new document with one new wrinkle:

There are more advanced functions that you can do in CASCADE. Some of them are explained in the Manipulating Document in CASCADE document, and some others you will find as you explore CASCADE.