Digital Humanities

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.

Northeastern University Library Receives Two National Endowment for the Humanities Grants

August 8th, 2018 – The National Endowment for the Humanities has awarded Northeastern University Library a $500,000 Infrastructure and Capacity-Building Challenge Grant. The funded project – Research Infrastructure for Digital Scholarship – will further propel Northeastern’s commitment to digital scholarship, the synthesis of archival materials and data, and experiential education. This challenge grant will expand the Library’s technical capacity through the creation of four new staff positions to undertake technical development, data design, and semantic data integration.

Northeastern University Library also received $197,000 from the NEH’s Institutes for Advanced Topics in the Digital Humanities program to support “Word Vectors for the Thoughtful Humanist: Institutes on Critical Teaching and Research with Vector Space Models”, a series of four three-day institutes that will explore the use of word embedding models for textual analysis.

Formed in 2013, The Library’s Digital Scholarship Group has undertaken several important digital humanities projects, including Design for Diversity, Our Marathon, TAPAS, and the Women Writers Project. This challenge grant will continue to support these projects, as well as provide support for the recently announced Boston Research Center, which will be housed in Snell Library. The director of the Digital Scholarship Group, Julia Flanders, will provide leadership on both grants, and Sarah Connell is a co-director on the “Word Vectors” grant.

“In many ways these grants recognize and reward the great progress we’ve made over the past five years in establishing the Library as a significant research partner in the digital humanities at Northeastern, and affirm Northeastern’s status as a leader in this space” states Patrick Yott, Associate Dean for Digital Strategies and Services.

“We deeply appreciate this major support from the National Endowment for the Humanities, and are truly excited about the additional projects and overall capacity this funding will underwrite in the Library and across Northeastern,” said Dan Cohen, the Dean of the Libraries.

How one prolific Wikipedian is giving voice to pre-20th century women’s stories

This post was written by Cassidy Villeneuve on March 28th, 2018 and originally published on wikiedu.org As part of Women’s History Month, we’re looking at how our programs are helping to close Wikipedia’s gender gap. So far, we’ve featured work by students in our Classroom Program, who have improved Wikipedia’s coverage of women directorswomen in STEMwomen in academia, and more.
Visiting Scholar Rosie Stephenson-Goodknight. File:Rosie Stephenson-Goodknight.jpgVGrigas (WMF), CC BY-SA 3.0, via Wikimedia Commons. 
This week, we’re profiling Rosie Stephenson-Goodknight, a prolific Wikipedian and a participant in our Visiting Scholars program, a program in which Wikipedians receive access to academic sources they wouldn’t otherwise be able to use. During her years as a Wikipedian, Rosie has created and improved thousands of articles and has uploaded hundreds of images to Wikimedia Commons. She has also co-founded projects like Women in Red, an on-Wikipedia group dedicated to increasing the site’s coverage of women and women’s history, and the Teahouse, a project to welcome newbies into the editing community. In 2016, she was named Wikipedian of the Year, along with Emily Temple-Wood, for her efforts to improve the world’s most popular online encyclopedic resource. When Rosie joined our Visiting Scholars program, she gained access to a number of new sources through Northeastern University. This new access to previously restricted materials “adds another dimension” to Rosie’s workflow, she tells us in an interview about what she’s accomplished through the position. Rosie has already made impressive progress since March of last year, as seen on the Dashboard. Through the position, Rosie is focusing on improving biographies of pre-20th century women writers in the English language (with the definition of “writer” broadly construed). At this point in her Visiting Scholars experience, Rosie has created 194 new articles on Wikipedia, most of which are biographies of these pre-20th century women, and has added nearly 500,000 words. She estimates that in all of her time as a Wikipedian, she has created hundreds of biography articles of women. So what motivates Rosie to dedicate valuable time and energy to improving this resource that we all use? As Rosie explains, it all starts with one woman: her maternal grandmother, a textbook editor in Serbia and co-founder and president of the Yugoslav Association of University Women. She wrote for a living and published a number of monographs, essays, translations, and books throughout her life. In a similar vein, Rosie’s mother was a poet who earned a bachelor’s degree in English literature from Barnard and spent time in Columbia’s journalism school. These women writers had a significant impact on Rosie and their stories have been an impetus for her journey into public scholarship. <br< Rosie’s motivation for improving Wikipedia’s coverage of women’s history is a personal one, and so it’s not surprising that she has personally connected with stories of women she has written about. When asked about particular articles that have been most meaningful to her, Rosie points to the life of Deolinda Rodríguez de Almeida. Deolinda is considered the mother of the Angolan revolution. She was an avid writer, translator, poet, and teacher. She dedicated her life to the Angolan Independence movement, and was tortured and killed for her involvement. “She was so bound to her cause, to her people,” Rosie remarks. “She traveled from Angola, she was in Brazil, she corresponded with Martin Luther King, Jr. She touched my heart. And to know that the last days of her life were so wronged just — she just sticks with me.”
Eunice Eloisae Gibbs Allyn, who has a biography article on Wikipedia thanks to Rosie. File:Eunice Eloisae Gibbs Allyn.png, public domain, via Wikimedia Commons.
“Many of the women, their lives are important to me,” Rosie tells us. Eunice Eloisae Gibbs Allyn is another example; she was forced to write under a pen name (as were many women writers of this time) because her brother didn’t want to have a “bluestocking” in the family. By representing the lives and accomplishments of these women writers for Wikipedia’s worldwide audience, Rosie honors their names. While they were silenced in the past, we are not silent about them now. “Jane Doe, you deserve this,” Rosie says about the importance of writing these biography articles, “I know I can do it, and if I don’t do it, I don’t know who else is gonna do it.” There is an element of leadership inherent in the active Wikipedian role. Wikipedia encourages volunteers to “Be bold!” in their editing. And the site’s open-source nature puts the responsibility of maintaining its quality on volunteers. Part of what makes Wikipedia one of the most successful crowd-sourced knowledge projects to date is the avid commitment of editors like Rosie. Wikipedians rally to uphold Wikipedia’s purpose of benefiting readers everywhere by being the most comprehensive and accessible encyclopedia ever written. We’re proud to support dedicated Wikipedia editors like Rosie through our Visiting Scholars program. We look forward to following the impact that Rosie continues to make on the valuable resource that is Wikipedia.

“Storytelling, Archives, and Resilience”: reflecting on the role of community archives in the Boston Marathon bombing

On Monday, April 23 – five years and a week after tragedy struck Boston in the form of the Boston Marathon bombing – faculty, staff, students and members of the community gathered in Alumni Center to share reflections on remembering traumatic events and processing grief through collections and digital archives. The event commemorated five years of collecting objects and memories in “Our Marathon: the Boston Bombing Digital Archive,” a project that originated at Northeastern through efforts in the NULab for Texts, Maps and Networks, the College of Social Sciences and Humanities, and the Northeastern University Libraries. This year, faculty, staff and graduate students worked to migrate the site’s contents and metadata onto a new digital space under library management, giving it a long-term home where the collection can be preserved. Megan Barney, Lauren Bergnes Sell and David Heilbrun will reflect on their experience completing this migration in future blog posts. The event featured a panel of scholars whose work has been grounded in collecting and preserving so-called “grief archives,” including:
  • Dan Cohen, Vice Provost for Information Collaboration and Dean of University Libraries and co-director of the 9/11 Digital Archive
  • Ashley Maynor, award-winning filmmaker behind The Story of the Stuff and currently Digital Scholarship Librarian at New York University
  • Elizabeth Maddock Dillon, Our Marathon Principal Investigator and currently Professor of English at Northeastern University
  • Kristi Girdharry, the Our Marathon Oral History Project Manager and currently Assistant Professor of English at Johnson and Wales University
  • Jim McGrath, Co-director of the Our Marathon project and currently post-doctoral Fellow in Digital Public Humanities at Brown University.

Amanda Rust introduces panelists

Amanda Rust, Assistant Director of the Digital Scholarship Group, introduced the panelists to a packed crowd including university professors, graduate students, library staff, community members and project partners from outside Northeastern. As moderator, Cohen discussed findings and recollections from his experience as co-director of the 9/11 Digital Archive. He noted the emotional intelligence required to do this kind of work, especially in regards to community engagement. Maynor, the filmmaker behind The Story of the Stuff, set the stage by discussing the therapeutic effect of saving and organizing objects across various circumstances like family archives and spontaneous shrines. She noted that the value of such archives can be that they protect objects, put away for safekeeping; we know they are there, but we don’t have to look at them anymore.

Ashley Maynor

Girdharry and McGrath joined Maddock Dillon in a discussion of the process and outcome of the Our Marathon digital archive. Girdharry spoke to her work as Oral History Project Manager, where she discovered the clusters of stories that emerged from a wide range of personal experiences. She pointed out the different angles of narrative involved to tell a more complete story of the events of that day. Maddock Dillon, the project’s principal investigator, also highlighted the collective nature of the archive, drawn from crowdsourced objects and memories, and the collective labor that went into producing and maintaining it. These aspects, she said, along with the desire to enable the community to reclaim the narrative, drove the project’s name, “Our Marathon.”

From left: Jim McGrath; Kristi Girdharry; Elizabeth Maddock Dillon; Dan Cohen

As co-director of the project, McGrath has been highly involved in the archive from conception to its move to a new home in the library. McGrath initiated the collection’s move to a more permanent web space, and it is thanks to his persistence and care that the Our Marathon digital archive will continue to be accessible. During the panel, he pointed out the critical importance of community engagement in doing this kind of work, and how listening to the needs and values of multiple communities can correct our assumptions. He has written more about his long-term experience on the project at the National Council on Public History blog History@Work. After listening to the panel presentation, the audience asked questions about the labor and process of managing such collections and the role of the digital in future work. The Our Marathon: Boston Bombing Digital Archive is viewable at https://marathon.library.northeastern.edu/about/.