Using Functional Specification as a Tool for Project Communication

Digital projects involve complex collaborative networks, and they are at their strongest when they draw on the many different kinds of expertise that their participants have to share. At the same time, it can be challenging to draw together all of those different contributions of information, requirements, needs, and ideas in a single place. How do we bridge the differences in technical, cultural, and disciplinary knowledge within these teams, and create shared documentation that can evolve effectively during the project's full life cycle?

In the past few months, the Digital Scholarship Group has been experimenting with adapting the functional specification—a writing genre that originated in software application and system development—to serve as a tool for project communication. As part of the Northeastern University Library's recent LibCon event (a departmental sharing of projects and ideas among colleagues), members of the DSG presented a panel session that explored various aspects of this work from different perspectives. This post draws on those presentations to give an overview of the features, challenges, and possibilities of functional specifications in a digital humanities applied research group.

The genre of the "functional specification" in its original context covers several different types of terrain. As Senior DSG Developer Rob Chavez and Associate Director for Systems Patrick Murray-John described it, it captures important contextual information about the purpose and objectives of the project, the features and functions of the tool being developed (from the perspective of specific users and their needs), and the actors and entities (e.g. users, roles, and data) that are involved.

Functional specification definition flow chart

There are numerous benefits from gathering this level of detailed information at the inception of a project. At the level of practical planning, it provides concrete information that in turn makes it easier to develop design specifications, technical specifications, development plans, and tests to determine when a project has been successfully completed: if the functional specification describes a search function that returns results ranked by relevance, we know we're not done until that is working. Perhaps equally important for the DSG, the process of creating a functional specification fosters participatory collaboration among the project's constituents and prompts deep thinking about what the project is really seeking to accomplish, and helps the project agree on what it really needs before putting effort into building a working version. It also pulls together information that may be helpful for other purposes (such as grant-writing or publicity).

The functional specification also sits within a wider network of tools. Patrick Murray-John showed how the written document provides detail on specific features (such as searching, or viewing a map, or uploading a new file) which then gets translated into specific programming or design tasks which are stored in project management tools such as an issue tracker. While the functional specification provides a road map, the issue tracker provides a view of progress being made and enables the daily coordination of tasks and effort that are so necessary within a collaborative team. When a given feature is prototyped and eventually completed, the functional specification can then be used again as a confirmation that the real needs of the project have been met, and it can also serve as a place to record unfinished work that may have been out of scope—which in turn might feed into a future phase of the project's development, or support future fund-raising efforts.

Functional specifications, in their original context in the software development industry, typically operate within a fairly uniform technical team with a lot of shared skills and knowledge. As a result, the common practices and familiar features of this genre mostly focus on its practical and technical aspects: a data inventory, user stories, use cases, preconditions, the logical flow of operations from step to step within a given functional context. For the DSG, experimentation with functional specifications has focused on building out the genre in a few different directions. First, as DSG Director Julia Flanders described through the example of the Digital Archive of American Indian Languages Preservation and Perseverance (DAILP) project, the functional specification can function more effectively as a bridge between different parts of the project team if it includes deeper contextual information: not only user stories, but also detailed information about the motivations and investments of specific user communities, which in turn help the team understand how the project's data is shaped and why. In the case of the DAILP, understanding the differing needs of language learners, academic researchers, and language experts within the Cherokee tribes is crucial to technical design and decision-making at every level. As the DSG develops templates and guidance for project teams in writing functional specifications, we are putting greater emphasis on those topics and urging projects to use the functional specification as a prompt for early conversation. The DSG has also been experimenting with involving project teams more fully with creating the functional specification itself, rather than treating it as a purely technical genre. DSG Associate Director Amanda Rust discussed her work with the project team for the Civil Rights and Restorative Justice Project (CRRJ) to develop detailed accounts of the project's working processes and research, a process that has empowered the group to imagine the functional possibilities more concretely, and intensified their sense of involvement and investment in the development process.

As Senior Digital Library Developer David Cliff pointed out in his contribution to the panel, one of the important roles of the functional specification is to bring clarity and consensus about project scope, and to avoid miscommunication or the dreaded "scope creep" that can occur when functional requirements aren't clearly laid out at the outset. At the same time, as he and others noted, research projects like these are by their nature prone to change as they explore new possibilities. And similarly the DSG, as an applied research group, is always venturing into unfamiliar territory where precise time estimates are difficult.

10-panel description of the design process.

The functional specification must therefore tread carefully between attempting to pin things down too closely or prematurely, on the one hand, and leaving things so underspecified that a project is never done, on the other. Iteration plays an important role here: sometimes a project team needs to see a prototype of a search results display before they can imagine the full set of facets and options that will make it truly useful. To be most useful, the functional specification needs to be able to establish achievable interim goals while also keeping track of the project's largest vision. It is thus always a living and evolving document, and as one audience member pointed out in the panel discussion, it needs to make that evolution possible.

The Digital Scholarship Group has thus far developed three draft functional specifications and a draft template which also documents our emerging practices in this area. In the coming year, there are several areas where further research and experimentation will be needed. First, we want to create a fuller template and more detailed documentation of how and when different parts of the functional specification are most useful, situationally. Second, we want to continue to experiment with involving project teams in the authoring process. Third, we need to develop effective means for translating specific functions from the specification into concrete development tasks (to be tracked via GitHub). And finally, we need to tackle the question of versioning, and create transparent mechanisms for allowing the specification to evolve without losing its documentary value or creating confusion.

Greenhouse Studios at UConn and NU Library receive Mellon Grant for Sourcery app work

Sourcery logo  

The Northeastern University Library is excited to be involved in a partnership with Greenhouse Studios at the University of Connecticut to create Sourcery, a mobile application for sharing scans of archival materials. Greenhouse was recently awarded a $120,000 grant from The Andrew W. Mellon Foundation to support the continued development of Sourcery.

From Greenhouse Studios:

Launched in December 2019 by Greenhouse Studios, Sourcery is an open source, community-based mobile application that expands access to non-digitized archival sources. With the Sourcery app installed on a phone or laptop, a researcher seeking a document can simply type in the citation information, and the app will notify Sourcery-registered researchers currently working in and around the repository where the document sits. One of these remote researchers claims the job, calls the document from the archive, takes a picture of it from within the Sourcery application, and sends it directly to the requesting researcher. A custom, enterprise version of Sourcery, for use by archivists – especially during COVID-19-related library closures – will launch in late-summer 2020.

Funding from The Mellon Foundation will allow the Sourcery team to expand the geographical reach of the app, improve its user interface, and work with partners in libraries and archives to support the development of the enterprise version of the software. As a part of this effort, Northeastern University Library will host a virtual workshop series for institutional stakeholders in the fall of 2020, during which the team will solicit feedback and advice from stakeholders in the library and archives community.

Learn more about Sourcery and the grant here.

Archives and Special Collections Teams with Zooniverse to Crowdsource Boston Phoenix Index

For nearly 50 years, The Boston Phoenix was Boston’s alternative newspaper of record, the first word on social justice, politics, and the arts and music scene. Its intrepid journalists tackled issues from safe sex and AIDS awareness to gay rights, marriage equality, and the legalization of marijuana. Ads for roommates, romantic mates, and band mates—one could find all these and more in the newspaper’s probing, irreverent, entertaining pages. It ceased publication in March 2013, but in 2015 was preserved for posterity thanks to owner Stephen Mindich’s decision in September to donate the paper’s archives to the Northeastern University Archives and Special Collections (NUASC).

Screenshot of the Boston Phoenix 1974! Zooniverse Project pageToday, NUASC launches Boston Phoenix, 1974!, a new project that aims to make The Boston Phoenix’s content more accessible to researchers. Using Zooniverse, Boston Phoenix 1974! (left) will recruit an army of volunteers to create an index to The Boston Phoenix. Participants will be re-typing a large set of index cards that once helped Phoenix reporters find past articles. Volunteers will have the opportunity to take a deep dive into the arts, culture, politics, and topics of vital importance to Bostonians in 1974 by encountering articles such as “The Winning Ways of Mike Dukakis,” “Kissinger: Financing the Death of a Government,” “Lifestyles: Conversing with Lesbian Mothers,” “Changes ahead for Cambridge Rent Control,” or “Garrity on Busing: No Delaying Tactics." The nonprofit Zooniverse offers this platform to connect professional researchers with 1 million+ volunteers in order to enable research that would not be possible, or practical, otherwise.

Index card from a 1974 issue of the Boston PhoenixFor any researcher visiting NUASC to research Boston’s political, cultural, and social history between the 1970s through the early 2000s, The Boston Phoenix is always recommended as a primary resource, and it is widely used both for research and teaching. Pre-COVID, NUASC staff had previously digitized January-June 1974 of The Boston Phoenix for preservation purposes (right). These issues are now available, and provide a prime opportunity for revisiting this year—one filled with civil unrest, racial violence, and ubiquitous activism.

NUASC is offering this free (and fun!) activity for use in homes and classrooms across greater Boston (and nationally through the Zooniverse’s already-established volunteer network) in order to build a community of support—people who will be inspired to read articles they have transcribed and write about them on their favorite social media platform. When complete, the index will become a way for researchers to quickly pinpoint articles without having to browse whole issues. Ultimately, NUASC hopes to raise $250,000 to digitize the entire collection.

For information about the complete contents of NUASC’s collection of the Phoenix and some brief background information, please go to our portal page.

The Boston Phoenix masthead

Little Buttons, Big Movements: Processing the Mary M. Leno Button Collection

[caption id="attachment_275540" align="alignleft" width="398"]Mary M. Leno Button Collection NUASC estimates the collection contains about 5,000 buttons documenting a number of political and social movements, mostly since the 1960s. Original label for this box: “Peace Now; Bombs and Guns; Native Americans.”[/caption]

Northeastern Archives and Special Collections holds the Mary M. Leno button collection (Z09-016 and Z19-011), a personal collection of about 5,000 items collected by Leno which document a range of social issues and political activism from the second half of the 20th century and early 21st century. The materials in this collection complement other special collections in the repository, and give voice to local, national, and international solidarity movements. The Archives has recently developed a plan to organize and inventory the collection, and is also considering digitization.

The collection consists mostly of pinback buttons featuring text and graphics, as well as enamel buttons, patches, and ribbons. Most buttons with text are in English, but we have also found items in Spanish, Russian, and Japanese. The topics the buttons cover include women’s rights, LGBTQ rights, African-American rights, Native American rights, prisoners' rights, immigrant rights, civil rights, ecology and environmentalism, health issues, nuclear power, housing and development, war and imperialism, labor issues and unions, media power, consumer rights, and ageism, among other subjects. A large part of the collection consists of American political campaign and political party buttons, spanning back to at least 1916.

Despite spanning such a diverse range of topics, the majority of buttons are undated and typically provide little provenance information beyond manufacturing details. Text or graphics usually give some indication of context, but often we cannot place the buttons in a particular time and place, and know little about their background prior to donation. Because of this lack of context, we have decided to organize buttons by topic to the best of our ability. Most buttons were grouped into loose topics when they were donated. Apart from adding some additional topics and changing some language, we have decided to in large part retain Leno’s original organization of the materials.

One of the most interesting aspects of this collection is how many of the buttons address intersectional issues and activism. Buttons about eco-feminism, housework labor, environmental racism, consumer divestment, AIDS prevention, and political prisoners are just some examples of overlapping movements and topics. To accommodate this, we intend to inventory and record basic information about each button, to help users find specific items they may be looking for across topics. The hope is that this will support the discovery and research of intersectional issues and social movements.

We hope that by processing and enhancing access to the Mary M. Leno button collection, we can help patrons research and discover histories of social and political activism through archival objects. The collection is open for research, and we encourage you to come take a look when the reading room reopens. For more information, please contact us at archives@northeastern.edu.

[caption id="attachment_275541" align="alignleft" width="306"]Mary M. Leno Button Collection Buttons arrived at the Archives in several boxes, with multiple topics represented in each box. Original label for this box: “Multi-Cultural; African-Americans; Native-Americans, Prisoners’ Rights; Imperialism.”[/caption] [caption id="attachment_275545" align="alignright" width="373"]Mary M. Leno Button Collection A box of buttons documenting LGBTQ- and AIDS-related activism.[/caption]

Using PIVOT to Find Funding and Publishing Homes for Your Research

When it comes to finding research funding and publishing opportunities, PIVOT is a valuable resource to make the search a little easier. Interdisciplinary and current, PIVOT provides a variety of ways to access information about grants and calls for papers, and to identify potential research collaborators. The red bar at the top of the page allows users to search by Profiles of successfully funded research; browse and keyword search functions for publishing opportunities is under Papers Invited; and the Awards link provides details about awarded grants, researchers, and sponsors.

[caption id="attachment_275530" align="aligncenter" width="300"] The main page of the PIVOT database guides users on how to search for the latest funding and publishing opportunities for researchers.[/caption]

For new users to PIVOT, a good place to start would be to check out the menu options under Funding Discovery.

The tabs to the right of Funding Discovery allow you to search by text, sponsor, or keyword, and the latter provides a broad alphabetical listing of research topics.

For those that would rather see available resources in their particular research interest and check other related research subjects, users can explore an interactive feature that displays the scope of all available funding within the database. Click on the Funding Discovery link, then Take a Tour and browse by keyword to see how much money is available by research topic.

[caption id="attachment_275531" align="aligncenter" width="300"] This interactive tool breaks down how much funding is available for various fields or topics.[/caption]

As always, if you have any questions about using PIVOT, or any other library resources, contact your subject librarian.