How did we build version 2 of the platform? - BillionOysterProject/digital-platform-beta GitHub Wiki

If you'd like to fork this project or start your own community science open data app aimed at educators and students, you might be interested to learn how we built version 2 of the Billion Oyster Project Digital Platform. As the product manager and developer for the platform, I'm always looking to grow and learn from other organizations, and I'm happy to share what I know! Take a read through this page, and if you have any questions, feel free to reach out to me (Heather Flanagan) through Github or at: bop.digital.platform@nyharbor.org

Context for the original BOP Digital Platform and the redesign

The original digital platform was built as a part of a National Science Foundation grant to support our Education program. The core of this program is to engage educators and students in collecting oyster monitoring data as a part of the regular school day. Participating in Billion Oyster Project's research by collecting data serves as a powerful hook to students- they really value being able to contribute to a "real" restoration project- but what we want is for these outdoor field experiences to spark students' curiosity and drive their interest in asking and answering their own original research questions. (For BOP, the education piece of our work is crucial, because we believe that restoration without education is fleeting. We know that training the next generation of scientists and environmental stewards is the only way we'll restore New York Harbor, because it's going to be a multi-generational effort!)

This meant that while data collection was a key part of the platform, we needed other functionality as well. We needed a curriculum repository to give educators a path they could follow to teach their students the skills to do research, a data viewer that would give students access to data they could analyze in support of their projects, and a place to showcase student work.

Contractors built the original version of the BOP Digital Platform, and until I took over we didn't have someone with software development experience managing the project in-house. Having reflected on all the work we've done on the platform over the past couple of years, I think you don't necessarily need an internal team to build an app that reflects your org's goals and values, but it's crucial to have at least one person at your non-profit who knows what questions to ask the designers and developers and can give them the information they need to build the tool that will work best for your participants.

In our case, we didn't get the user experience quite right the first time around. We hadn't conducted actual classroom testing, and since the designers and developers didn't have education experience, they didn't know some of the nuances of what it's actually like to use technology in a room full of 30+ sixth graders (and we hadn't adequately communicated those challenges to them). We also didn't insist on automated tests or robust rounds of manual QA, which meant that students and teachers were often the people who found bugs- not ideal for building trust with our users.

Having both worked in software development and as a classroom teacher (and having written curriculum and trained teachers for BOP in my previous role), I felt like I had a better idea of what a teacher might want in an educational tool, but I've had plenty of surprises along the way! That's why I think building relationships with your users, spending lots of time observing them and gathering feedback, and creating multiple communications channels for them to reach you is key. Teachers have such a heavy workload, and classroom technology has amazing potential for them and their students, but whatever you build needs to support them, not create more work for them!

Keeping this in mind (along with certain architectural details- I go into those in more detail on the System Architecture page of the wiki), I eventually undertook a redesign of the platform, but first I focused on setting up systems that would foster communication and collaboration with my colleagues and our participants.

Communication and Project Management Systems

Internal Communications and Systems

I wanted to create transparency about work on the platform so my colleagues had as much information as they needed to help shape it, both as users and as representatives of our participants. The two key tools I used for this were Trello, a project management app and Slack, an internal messaging app that lets you organize your communications into "channels."

Trello allows you to create "lists" of "cards" (sort of similar to a Kanban board)- a team of users can add cards, attach links and images to cards, or follow cards to receive updates. I created two boards for the platform- one functioned as a backlog of feature and change requests, organized into categories like "Curriculum" and "Data Entry," and one that tracked the progress of specific action items. For the backlog, each request got its own card, and colleagues could add cards directly to the board or submit them via the "digital_platform" channel in Slack. I organized the action items board in a loose approximation of a Kanban board, with columns identifying "To Do," "In Progress," and "Done," but without deadlines (as the only person working on the platform and no funding for external contractors beyond 8 hours a month of maintenance, the only deadlines I actually had were self-imposed).

I also integrated our external contractors' customer support issues in Jira (an issue tracker and project management app that is a little more robust than Trello) with the Slack channel. Since the platform contained a bug report feature that would immediately send reports to Jira, the Slack integration meant that I would get notified automatically when someone reported a platform bug, or when the external developers commented on our changed the status of an issue- and everyone else on the Education team could also see that information at a glance.

Later, I integrated both the original platform's Github project and the redesign's Github project with the Slack channel as well. This allowed the whole team (and anyone at my organization who was interested) to see when bug fixes or new code were pushed. (Slack's mute function helped deal with potential over-notification problems!)

Participant-facing Communications

Before I took over the platform, I'd written the help documentation, but I wanted to create additional ways for participants to learn more about the platform and get their questions answered. When schools get involved with our Education programming, they send one or two teachers for a one-day Oyster Research Training session. So I created an hour long practice session and presentation to address teachers' questions in person, and I built the presentation as an ArcGIS Story Map called, "The BOP Digital Platform Quick Guide." (I've found that Story Maps are a great tool to use because they allow the reader a way to quickly scroll through a presentation or piece to browse it, but you can include lots of links and detailed content for users who want to spend more time.)

Helping run the full day of these monthly trainings, including the actual data collection in the field (instead of just popping in for my presentation) allowed me to form a connection with all of the new participants, answer their questions one-on-one, and better understand their challenges and worries about teaching in the field. And I think it made participants feel more comfortable about coming to me about customer support issues and sharing their feedback, since we'd had this face-to-face interaction. If you're building your own community science app, you may not be able to interact with all of your participants in person, but I think it helps to meet people and welcome them to the project in whatever way you can, whether in person or online, so that they have a friendly face to go to if they encounter bugs or get stuck.

I was the only person doing customer support, so I ended up mostly responding to participants via email, but if I'd been a part of a multi-person team I would recommend using some kind of ticketing system for customer support so users' issues don't get lost in the shuffle. (I used Jira when I worked in a large, corporate software development division, but there are other options that might work better for non-profits or smaller organizations.) We had the platform set up so that customer support requests would get sent to the generic bop.digital.platform@nyharbor.org email address, but I generally answered emails from my regular work email address.

In order to address basic customer support questions, I also changed the language in the automated emails that got sent when a participant signed up, when their account was approved, when they submitted data, etc. By including links to the Quick Guide and help documentation, and by providing more information in the welcome emails, I received fewer basic customer support questions.

If you have this option, I found that a good way to get participants to let me observe their use of the platform was to offer to come to their school in person when they contacted me with a particularly tough customer support issue. It gave me the opportunity to get user feedback in person, and by giving participants the chance to help shape the platform, it seems to have deepened their investment in the program.

When I decided to start work on the redesign, I timed my initial work so that I could preview it at our Spring Kickoff, a reengagement event designed to get participants ready for the coming field season. I sent out a survey to all of our participants in advance to learn more about their challenges with the program and platform, and I scheduled a few classroom visits to follow up on these findings so that I made sure we could address their concerns at the kickoff. Then, I created a presentation that made sure to highlight how student and teacher feedback had translated into new designs.

Identifying new goals for the project

Once I'd created communications channels for soliciting and receiving feedback, and spent time reviewing this feedback, I initially started by making changes to the platform's original codebase. (This process was delayed because the contractors controlled all of the systems used to maintain the platform and took a long time to give us the necessary access- if you undertake a project like this, make sure someone at your organization has admin access to things like Amazon Web Services and Github!)