Technology

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.

February Workshops in the Recording Studios: Learn Podcasting, Video Recording, Sound Design, and More

Looking for a place to record your podcast or video project? Need to develop your media production chops? What is good sound design? The expert staff in the Library's Recording Studios can teach you how in our multi-part workshop series beginning February 4. Click each flyer to enlarge:
 
Flyer describing Intro to Snell Studios workshops Flyer describing Intro to Podcasting workshops
 
Flyer describing Intro to Video Recording workshops Flyer describing Intro to Sound Design workshops
 
Use the links below to register for a workshop. Each workshop is offered on multiple dates—click on "Show More Dates" for each workshop to see when it will be offered!

Register:

Questions? Please contact Isaac Schutz, the Recording Studios’ Co-op, at i.schutz@northeastern.edu or 617-373-2465.
 
Students record video in the Snell Library Recording Studios        

Open Access Week Breakfast with David Weinberger: Thursday, 10/25!

Don't miss the keynote event of Open Access Week! Join us tomorrow morning from 8:00-9:30 a.m. for continental breakfast with our special guest speaker. David Weinberger is an American technologist, professional speaker, commentator, and a senior researcher at Harvard University’s Berkman Center for the Internet and Society. At the Berkman Center, David writes about networking knowledge and the effect of technology on ideas, business and society. He is the author of Too Big to Know, Everything is Miscellaneous, and Small Pieces Loosely Joined, and a co-author of The Cluetrain Manifesto.

Open Access Week Breakfast with David Weinberger

When: Thursday, October 25, 2012, 8:00-9:30 a.m.

Where: Cabral Center, West Village F

All are welcome!

     

Apply Creative Commons Licenses to Your Work with These Tools

Next time you're writing a paper, putting together a presentation, uploading a video to YouTube, or updating your website, why not tell your audience that you've decided to expand access to your work? With a Creative Commons license, you keep your copyright but allow people to copy and distribute your work provided they give you credit — and only on the conditions you specify.

If you have a PC and use Microsoft Office products like Word and PowerPoint, you can get a free add-in that makes it easy to include a Creative Commons license. Read more about it and download the add-in here: To include CC licenses elsewhere (anywhere!), the Creative Commons license chooser offers the ability to select the criteria you want your license to include and then provides you with the relevant text and an image to use (including HTML for use on the web). In addition, Creative Commons offers best practices for marking your work as CC-licensed in a variety of formats, including images and video. Sites like YouTube and Flickr also offer the option of applying a Creative Commons license when you upload your stuff. For even more info about Creative Commons, check out their website.

Snell gets a permanent upgrade!

In addition to the already available group study rooms located throughout Snell, four new media:scape tables were recently installed on the first floor for all members of the University to use. These high-tech tables are an efficient, modern approach to increase effective group interaction by allowing all students to engage in the project and freely share their ideas. So how exactly do these media:scape tables work? Each station is equipped with one or two monitors which students can use to display their laptop screens by simply plugging it into a central outlet. With a stylish layout of tables and chairs, students can both relax and communicate with one another while their group work is projected on the large monitor. Through these new media:scape tables, information is now easier to convey and display to group mates all while students are sitting in one of the comfortable ergonomic seats. What is so unique about the new media:scape tables is that they are a direct result of what Northeastern students requested! Last fall, Snell sampled a table for about three months to observe how often students used it, if at all. The feedback that Snell Library received was overwhelmingly positive, confirming that the media:scape tables would definitely be a worthwhile investment. These new media:scape tables offer students an innovative, learning environment, which is what the Library aspires to create. Currently, the Library and University is eager to explore more ways to utilize its study space and equipment, but these permanent stations have definitely put us on the right path to do so. If you've used one of our tables, let us know about your experience by filling out our data collection survey! Click here to fill it out. For more information about the media:scape stations, please visit here!