Writing Reports In Software Engineering
During the past couple weeks I've been working with my team on generating a ~20 page experience report on our university team project. The report is on around 7 months of development time including planning meetings.
The lecturers are looking for a document that reflects on specific themes encountered during the development of our project. One of the examples given are if we found we had to drop a feature during an iteration, discuss why it had to be dropped. Had we given ourselves too much work? Was the feature harder than expected? Was it unnecessary?
I've found that reflecting on our software practices in such a detailed way to be an unusually difficult task. I knew this report was upcoming throughout the entire year, but expected it to be relatively easy to come up with a 20 page discussion on 6 months worth of development time. Obviously it's possible, otherwise the course coordinators wouldn't expect it.
Part of the difficulty is due to a lack of detailed documentation of what events transpired throughout the project. Roughly once a month we conducted a retrospective, but the problems (and improvements) noted in each were not particularly detailed due to us having intimate experience with what we were talking about - 6 months later though, that detail is a bit hazy. I would recommend anyone who has to write a report at the end of a development process to DOCUMENT, DOCUMENT, DOCUMENT. Write down everything that happened, good or bad, when it happened.
At my internship last summer we conducted retrospectives that were indicated on our calendars to last an hour - they rarely lasted more than 15 minutes. I'm not entirely sure why we as developers (in my experience) dislike looking back on our mistakes or problems - but it seems like a concerning issue. Retrospectives exist for a very good purpose: we need to reflect on our initial mistakes, identify their root causes, and prevent them happening in the future. So why were developers of all experience ranges (senior to intern) happy to skip over these reflections with superficial discussion?
Perhaps it was in pursuit of the next challenge - I could tell this a big reason for myself as well as another developer to view the retrospective as an unfortunate task. We were eager to jump onto the tickets of the next sprint. We didn't want to discuss problems we had already solved, and probably mentioned to some degree in the daily stand-up meetings.
Perhaps it was in avoidance of admitting that mistakes were even made in the first place. We made it over those hurdles - don't mention the fact we stumbled as the race started.
I'm sure someone of more experience in the matter would be able to provide a deeper insight into retrospectives and how to handle them, but I should probably get back to writing my report...
If you enjoyed this post, please check out my other blog posts.