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 calenders 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...
Check out my other blog posts! If you found this post interesting, feel free to let me know either on Twitter (@Isaac_M_Jordan), or in the comments section below.
Enjoyed my post? Sign up to the newsletter to receive a small email when I post. No spam, I promise.
Seth Brown on April 11, 2016, 3 a.m.
Since 2002, I've been using TWiki to log things. Very useful when working as a contractor to log times worked and things work on. Recently, I've gone back to programming and I log requests, bugs, fixes etc. I work alone so I don't have the benefit of having others to discuss my code, which, I am sure, would make me a better programmer, but I feel the effort of writing things down certainly makes it easier for me to remember and work things out.
I tell people this is my super-power, having my own personal wiki. I always install a copy at each company I have worked at and encourage others to continue using it when I move on.
As TWiki not only time/date stamps each entry but also implements revision control automatically on each entry and provides a search features, I believe every programmer/system administrator can benefit from having it installed.