Instructions

This template is the vehicle for complying with the OSP Procedure for Feature Requests. Each element of the template is keyed to the step that the element fulfills, in whole or in part. For example, a (1) in the heading indicates that this portion of the template must be filled out in order to complete step 1 of the proposal approval process. The Proposal for Enhancement page you create in Confluence based on this template will provide a locus for community discussion of the enhancement. A primary goal of this process is to capture institutional memory about what decisions were made during the design phase and why.

The Proposal for Enhancements template has two parts, the Functional Description and the Technical Specification. The expectation is that the template will be fleshed out over time as plans for the enhancement develop through community discussion.

Part 1: The Functional Description
The Functional Description should be created before the enhancement is first proposed, usually by domain experts such as instructional designers, educators, or project leads. As much as possible, it should paint a picture of what the enhancement is and what it will allow the user to accomplish. Focus should be on functionality rather than implementation. While the Summary, Rationale, Origin, and User Stories are required before the proposal is presented to the community, diagrams, mockups, and the "Functional Details" and "Interactions and Implications" sections may be added later as the proposal matures.

Part 2: The Technical Specification
The second part of the proposal, the Specification, should be filled out once the feature is clearly defined but before coding begins. While the first part of the proposal should usually be filled out by domain experts, the specification would normally be written by a developer or other technical person.

Please remove these instructions from your document.

Part 1: Functional Description

Finer Grained Document-Level Matrix Permissions (1)

Summary (1)

The proposed functionality will provide shared control at the document level to a group of specific users. Moreover, the functionality of adding a private comment is enabled which is visible only for the owner of the document and the creator of the feedback.

Rationale (1)

The proposed enhancement is a requirement to enable interns to reflect on their hospital training, the difficulties they face in their trainings. They have to fill out forms prepared by a tutor where they can report their reflection on their trainings. The forms are organized in a matrix where columns are trainings and rows are competencies. The proposed enhancement is to allow reviewers to review the forms at the cell level with reviewing permissions at the document level. Currently, the permission to review a form was only at the cell level which means a reviewer had access to all forms of a cell or to none. Because these reflections can involve other residents and staff members' interaction, the resident wants to ensure that only a restricted group of people can review their reflection. In addition, the reviewers are chosen by the intern who can add new participants or remove the reviewing rights at any time. The proposed enhancement ensures confidentiality at the document level in a cell matrix and is a step toward more collaborative work between peers.

An appendant feature of the proposed enhancement is the new review type "private feedback". Currently, reviewers can give feedbacks to documents which are visible for everyone who has access to the cell of the document. The new type of private comments is only viewable by the writer of the feedback and the owner of the document. Using private feedbacks, reviewers feel freer to add constructive criticism which again enriches the collaborative work.

Origin (1)

The origin is the Faculty of Medicine at Université de Montréal. The department wishes to foster collaborative learning by sharing and exchanging reflections with other colleagues.

User Stories (1)

Actors and Stakeholders

• Residents: medicine residents, interns.
• Tutors: a person who is a senior resident or a doctor.

Stories

• Invite a group of individuals to review a reflection. As a resident, I want to invite a restricted group of people review my reflection. Only these people will have the right to see that the document exists, to read the document and to comment it.
• Read and comment a reflection. As an invited person, I want to see that the document exists and I want to read the reflection (the content of the reflection), and review the reflection.
• Read a reviewer's private comment. As a resident, I want to read the reviewer's feedback on my reflection. This comment is not visible for other reviewers and cannot influence them on their feedbacks.

Functional Details (may be added after community demo) (1)

The resident who wishes to invite individuals will select them from a list of possible individuals. The invited people will only see documents they are granted to review and can add private comments which are only viewable for the resident.

Interaction and Implications (1)

A participant can grant reviewing permissions by document (filled form) in a matrix cell. A reviewer can review only the forms that were granted by the owner of the forms. Reviews are not viewable by everyone with access to the matrix cell but only by the reviewer and the owner of the document.

Diagrams and Mockups (3)

(To be done) Include any ERDs, flowcharts, sketches, mockups, etc.

Invite a group of individuals to review a reflection.

Read and comment a reflection.

Community Acceptance (4)

Elements of this enhancement have been raised on sakai-dev@collab.sakaiproject.org and portfolio@collab.sakaiproject.org. Also, during the meeting of Monday 2009-02-03 11 am, we discussed details and that seem to raise interests among participants.

Part 2 of the Proposal for Enhancement Template: The Specification
The specification should be filled out once the feature is clearly defined.

Specification Template (5)

Behavior

Describe each specific behavior of the feature in the present tense as if the feature were implemented perfectly. Use precise, objective language to describe ideal behaviors against which actual behaviors can be evaluated.

In the case of conditions and behaviors that must be evaluated independently, they should be presented in a two-column table as below.

When there are workflow behaviors (steps) that must be evaluated in sequence, they should be identified with prerequisite conditions, behavior, and post-behavior conditions as below.

Workflow Steps

Interaction

List any entities or actors that are used or affected by this feature. Each should link to an entry in the OSP Terminology page.

Quality Metrics

Describe any non-functional requirements of the feature, such as usability, performance, or design. Provide objective and, where possible, quantitative measures against which actual implementations can be evaluated.

Assumptions

Provide any assumptions about implementation path, availability of other required features, schedule concerns or otherwise.

Outstanding Issues

The Outstanding Issues section is a placeholder for the evolution of this specific feature. It should mention any explicit design or implementation decisions that are pending. There must be no outstanding decisions as of the confirmation of the feature as a requirement.