Skip to end of metadata
Go to start of metadata

The functional team guides the development of the CollectionSpace functional requirements, including procedures (e.g. acquisition, loans) and administrative interactions (e.g. search, user management), and overall system usability.

Process Overview

The process begins with information gathering. Sources include published museum standards (e.g. SPECTRUM and Cataloging Cultural Objects), domain-specific guidelines (e.g. the Visual Resources Association), use cases submitted by colleagues and implementing institutions, and notes gathered at the two community design workshops held in March and May of 2008.

The information is then synthesized to create a requirements page. Each requirements page includes a definition, list of requirements (some of which may or may not be developed), links to existing standards and guidelines, and relevant schema, use cases, user stories, and wireframes.

Sample requirements page: Acquisition Requirements
Sample schema page: Acquisition Schema

The requirements page is refined as items are considered for including within a release to break down the entirety of the functionality into smaller pieces. A release-specific functionality page is created which includes a brief discussion of the functionality, workflow documents, wireframes, and user stories (short prose descriptions of functionality).

These release-specific functionality page includes a breakdown of "must-haves" for the release, "nice-to-haves," and elements of the overall functionality that are out of scope. These determinations are made based on conversations between the functional team and active implementers.

Sample release-specific functionality page: Vocabulary Requirements - Release 1.7
Sample user story: User can add one or more value instances to a repeatable group of fields

Throughout the process, functional team members work with and respond to feedback from the design and development teams in order to refine and clarify the requirements.

Use Cases

Use cases describe real-world issues faced by collections-holding institutions that assist with the development of CollectionSpace functionality and interfaces. Use cases may take the form of a list of requirements, or a prose description of a scenario or process.

Sample use case: Acquisition Use Cases

Schema

Schemas describe the contents and structure of the records that represent various entities in the CollectionSpace system. Schemas are composed of individual information units ("fields" or "data elements"), which are usually organized into groups of related information units, known as information groups.

Each information unit contains a number of attributes, including its definition, default data type, whether it is part of a set of fields, and whether it is repeatable (on its own, as part of a set, or both).

Sample schema: Acquisition Schema
List of standard data types: Schema Data Type Definitions

Each schema page includes two types of schema: one full schema, which describes the intended functionality of the procedure or administrative interaction, and one release-specific schema which describes the functionality as expected for a particular release.

Keeping Schemas in Sync

To ensure that a change in the schema decided on by the functional team is properly implemented by all the layers and the test-plans and documentation are updated to reflect this change, the following process has been set up:

  1. A required change to the schema is identified
  2. Megan updates the full and release-specific schema on the wiki to reflect the change
  3. Megan creates a Jira describing the change, assigning it to a services developer and cc'ing a UI designer
  4. Megan sends out a mail to the work list detailing the change so everyone has a chance to discuss any issues or potential complications
  5. UI design creates sub-tasks for wireframe and html update
  6. After the service layer has implemented the changes, the issue is assigned to the server-side interface layer, with a comment including the IDs they have chosen
  7. After the server-side interface layer has implemented the changes, the issue is assigned to the client-side interface layer, with a comment including the IDs of the fields based on the Selector Naming Conventions
  8. The UI layer implements the changes, and assigns the JIRA to QA if everything seems to be working as intended
  9. Documentation! (in most cases, the updating of the wiki-schemas that Megan does will be reasonable documentation)
  10. QA makes changes to testplans if necessary and closes issue
  • No labels

1 Comment

  1. Thanks for documenting this work flow. I have two questions/suggestions and I think have found one typo but want to cinfrm rather than making the change.

    Question/suggestion 1: Regarding point 4: it would be helpful to outline the process and tools in reference to "so everyone has a chance to discuss any issues or potential complications". Should the conversation be held in one space, such as in the JIRA you've opened? Or perhaps the coversation is on IRC and someone copies the basic issues into the JIRA? It might be helpful to capture the decision at the top of the JIRA comment section along with the date of the decision.

    Sometimes a schema is revised based on the discussion: in that case does this process start again, or do the iterations continue as part of the original conversation? Relatedly, on the Schema page can we have a link to the relevant JIRA and also can we date the schema iteration, maybe using a version number that includes a date? (In contrast to the page last edited which could be quite different from when the schema was last edited).

    Question/suggestion 2: Regarding point 5: It is likely that the services team will need to create sub-tasks also. And perhaps the server-side (App) team.

    Typo? in 7, I wonder if it should read "After the server-side interface layer has implemented the changes/..." since the prior point referred to this layer.