At Wikimedia, for the last months I’ve been on and off rewriting our on-wiki technical Gerrit/Git/Code Review documentation.
Code review related documentation
That included improving the onboarding steps like setting up Git and Gerrit (related task; 135 edits), the contribution guidelines and expectations for patch authors (related task; 28 edits), and to some extent the guidelines for patch reviewers (related task; 23 edits).
Among the potential next steps there is agreeing on a more structured, standardized approach for reviewing code contributions. That will require engineering and development to lead efforts to have teams follow those guidelines, to establish a routine of going through unreviewed patches, and other potential iterative improvements.
On paper
I’m not a person carrying around a laptop and don’t use mobile phones much. The more text/comments to tackle (or seperate pages covering related topics), the more I prefer working on paper. (That’s also how I started high-level planning the GNOME Evolution user docs rewrite.)
It might be archaic but paper allows me to get an overview of several pages/documents at the same time. (I could probably also buy more or bigger screens?) I can mark and connect sections that are related and should not be in four different places (like Troubleshooting related information or operating system specific instructions). Plus trying to be accountable and transparent I end up performing lots of small atomic changes with a proper change summary message so I can cross out sections on paper that are done on the wiki.
Paper especially works for me when thinking about topics that still require finding an approach. So I end up in the park or in a pub.
In a future blog post I’m going to cover what I’ve learned about aspects and issues of code review.
