Devlog - A Diary (not only) for your GSOC project
I have been quiet for some time (part of the reason is that I was able to attend ScalaDays Copenhagen), and I realize that this post comes just a little late for the start of the coding period of GSOC. However, I hope these tips will still be helpful to you for maintaining a development diary in form of a simple blog you can show off at the end of the summer.
I just released a DevlogTemplate to simplify the setup. It’s not a huge deal, but it may help to focus on the main goal of your summer project while still having a platform to keep track of your progress. There are plenty of tutorials out there on how to set up a Jekyll-based blog for Github Pages, so this is not going to be a technical tutorial.
The idea for the template and this post grew from the GSOC mentor mailing list where we discussed ways to improve communication between students and mentors. Someone suggested a continuous feedback from the student in form of a dev diary, a condensed form of a more detailed dev blog.
Others were quick to chime in on the discussion and point to existing blogs, such as Karan’s devlog for the TARDIS project. At this point, I want to say huge thanks to everybody involved in projects like these, and in particular to the students and mentors that suggested this approach. The template is derived from this, and more references can be found on the Github page.
What is this all about if not a set of instructions on how to run your dev diary, you may ask. In the core, I want to point out a few ways how to structure the content of your blog, what to present, and why you should do it. We at MovingBlocks do not prescribe our students to use the template (or any particular form of documentation) but rely on agreements between students and mentors. However, we hope that some participants will pick it up.
Why should you consider keeping a Dev Diary?
First of all, it is fun to see what you achieved over the last days, weeks, months. It can keep you motivated even if the visual outcome is very small at times. Remember all the bugs you reported and investigated? All the small PRs that led towards a bigger goal? In your dev diary, you can see all these small steps you took!
In addition, your Dev Diary functions as a comprehension of your project (or at least will help you wrapping everything up in the end). Spending little time (nearly) every day prevents you from writing time-consuming recaps and summaries each week (or last minute after several months).
Probably not the most important aspect is that you can share your progress with others, e.g., make it available to members of the community your are collaborating to. A dev diary is just another form of documentation, co-existing with project boards (like Github Projects), detailed blogs (see Nihal’s blog), or forum posts/threads. If you are not actively documenting your work, you should consider getting started with this little gem.
What is going to be presented there?
At a bare minimum your pull requests, issues you reported or investigated, and pieces of documentation and reference you found of interest should be collected. You may want to add a few words on the context and what is contained in your activity. Having a bullet point list of each weak (or entry) is sufficient, and you can improve your diary from that point forward.
Karan’s devlog categorized by dates. Each section covers about one week, the
longer bonding period is briefly summed up in the first group.
Your posts can be enhanced it with screenshots or videos, class or architecture diagrams you’ve sketched, or technical details you want to point out. What was puzzling to get right? What did you learn while working on a problem? Is there anything valuable to others? Were you able to apply something you just learned somewhere else? I bet you can come up with even more ideas.
How should it be structured?
This depends a bit on how you are planning to use your dev diary. If it is just for you personally, you can do whatever you want.
Last year’s GSOC students seemed to stick to a weekly report style, where entries were grouped by coding week or some period of time. Each week, the student wrote one or multiple posts about the latest progress. These entries can then be discussed in the next meeting with mentors - just a like an agenda you set up.
Mikhail’s devlog sorted by GSOC coding week.
Another approach is to structure single entries by coding period or working phase. For a Google Summer of Code project you would start with the bonding period, followed by the coding period(s) leading towards the evaluation(s). If you are working in an agile team using Scrum you could track your personal contributions per sprint in your diary.
A dev diary with entries categorized by feature and/or project phase.
I can only encourage you to get started with your personal devlog for your Google Summer of Code project (or any other project). I hope you found these tips helpful, and, as always, I appreciate any feedback - you can reach me via twitter . And please check out the devlog template and help to improve it!