Disclosing Bugs - requiring a project roadmap

Over on Facebook, a fellow CS educator ¹ made a comment on something he wanted to try with his students this summer: having the students pre-disclose bugs when they submit their projects.

The post was asking for any links to "the literature." I can't speak to that but I I've done something similar to what the post was asking about so, as per usual, I thought I'd write about it here. It may not be "research" but I'm more interested in teacher practices than ivory towers anyway so here goes…

At a very basic level, I ask my students to provide a roadmap to any project they submit - usually in a readme file. I basically ask:

• How to use the project
• What's cool and I should make sure to check out
• What doesn't work, where were the sticking points and what's the status.

I tell my students that when I test the project, I'm not "out to get them" and by their telling me how to navigate the project, it makes sure I see things in the best possible light. I also tell them that I will be more harsh on bugs that they don't tell me about - particularly bugs that only occur some of the time.

I also encourage (and sometimes require) that students maintain a changelog in their repo and also sometimes encourage them to have a todo list and list of bugs and for longer projects, I expect to see these and the readme updated over the course of the project (which should always be up to date on GitHub, Dropbox or wherever the project is living).

When the students provide a good write up it makes evaluating the project much easier.

When students buy in, they're hopefully thinking more deeply about their projects in terms of design and implementation and also from the point of view of someone else using their product. When they maintain the readme and other files over time, it also enables me to better support them.

So, does this work? Yes but with some caveats. It works better once the class and teacher know each other. If the students trust the teacher they're more likely to be open and honest when they write up the project. On the other hand, there will always be some students to "phone it in" and do the bare minimum in terms of writing up their projects.

The bottom line is that having the students do this is has a low cost and is beneficial to both the students and the teacher. When it works, it's great and when it doesn't, it's still pretty good.