Version control for visual learners

Editor's Notes

1. Hello (And thank you for that) I’m a self-taught, second-career developer who has managed to try on a lot of different hats. Today I’m going to talk about a problem I encountered as I started to shift from scripting to front-end roles, how I developed a solution for my problem, and what can be learned about communication and allowing ourselves to build the tools we wish we had. This talk is a little about tools and a lot about opening yourself up to making the software you need to make your Git-workflow work for you.
2. Not everyone uses git the same way so before I talk about the git-venture we’re about to embark on together, we should take a moment to review my ideal workflow and where I was as a Git user when I started this journey. My use: I used Git for the first time the way many do - a loving and patient friend sat me down and explained “the five commands I would need to know” (that’s add, commit, push, clone, status). After 54 requests over messenger of “tell me one more time?” my friend reasonably decided it was time for me to have a cheat sheet. I have added to it piece by piece as I needed but never did a “Git intensive”. As you might guess, I had some discomfort with the “time travel” aspects of Git. My strategy was to keep things linear (or at least going the same direction!). At the time I could push, pull, and checkout but anything fancier than that was out of the question. I’ve included what my typical Git workflow was at the time and listed steps you may have in a more Git-integrated workflow so you can see where I was when I got started. My work had mostly been scripting up to this point but as I started to do front-end web work (visual work), I struggled with the design aspects - as many know, often a client has a much stronger idea of what they don’t want than what they do! - and I had to force myself to revert to previous versions - after many of these, I began to wonder if I could do to make this back-and-forth easier. I relied on my commit messages to guide my “time travel” and researched how to write strong commit messages but, because I was making such small changes & experimenting, I found myself struggling to find the *right* commit to check out. Started wondering if there was a better way.
3. Before I was a developer, I was a lab geologist whose work relied heavily on photo documentation of rock orientations… before that I was building Mars maps - also visual! I am a strong visual learner and find that I can take in information very well in a visual form. While I was thinking about my “timetravel” problem, I contributed to an Outreachy project (creating a dashboard) in a language I was new to and realized that when I was learning anything else new (as many of us need to be, all the time in programming!) I really had difficulty imagining the changes described on a ticket and wished that I could see what the dashboard had looked like in the past as I was imagining where it was going - the cognitive load of having to both imagine and learn were weighing on me. For me and others that are aided by visual cues, there was a hole in the documentation. Reaching out to the devs in my project, I learned that it was unusual to keep screenshots. Huh. So the industry doesn’t think like me. I could have felt bad about this, but I’m a big fan of letting your user’s needs and your project’s needs shape your documentation and I’ve internalized just enough of the hacker ethos we all aspire to to feel I should be pushing forward and *making something* so I started thinking about what might have helped me and all the other Veronica-similar folks who would come along.
4. Slide 4:: Learning about design the hard way…. Opens me to new ideas My next project was where I started to take action. Although I was hired as a web developer, many of my tasks relied on design skills that I didn’t have! While I googled and imagined icons and layouts (etc) and tried to grasp what would make a website useful, appealing & intuitive to users, I made many, many mistakes. Often I would go to bed certain that I was on the right path and then wake up only to find that my layout felt like the web-equivalent of pairing polka-dots and plaid (and neither me nor my client was ready to be that bold!). Sometimes I would move forward for days only to find that my client - on seeing exactly what they had asked for - wanted to go in a different direction. (Who’s had that moment? We’ve all been there.) Above you can see variations of a logo I made for one client - at the time I made these, I didn’t know the research that design entails and after an initial conversation I was turning out variations and believed I was practicing design. Has anyone ever set out to build something without considering all the parts of the project that they didn’t know how to build individually? (Lots of nods here) Having a “reach” passion project is a great motivator but having to go back to “tutorial level” foundational projects as you start each component makes the process of learning and (finally) building long and slow. This is the position I was in as I tried to learn design principles “on the fly”. On the right, I made a (thankfully non-exhaustive) list of methods that designers use to research and determine the choice of action that would address their client’s concerns as effectively as possible. Probably good for all the devs in the room, if they haven’t considered how critical how *academic* the work of designers is - to just take a moment and let how exhausting this un-exhaustive list is. . You’ll notice that the steps I was doing are all the way down the list - I had skipped all the deep information-finding and gone straight to “let’s build stuff” (I had internalized some toxic ideas “ideas are cheap”, “make it or it didn’t happen” - that undersell the importance of foundational, investigative work that asks “what should we be building?). And because I wasn’t taking those steps, I was making many, many changes and reverting many, many times. All this iteration and re-designing after feedback put me in a special kind of version control hell - it was extremely hard to track these changes - with commit messages and *especially* with my memory. Having to throw myself into design (face first - the hard way) opened me up to new ideas about how to use Git.
5. The “back and forth” meant I had a lot of Git “time travel” to do and I was, again, relying on my commit messages. Two problems with this: (#1) we all know what happens to commit messages we’ve been working too long… (show xkcd) yes, there were some trash commit messages for me to decipher. As much as I researched how to make the most helpful commit messages I could (there are some guidelines!), I still fell into that dark place this comic references. CHANGE SLIDE Slide 6:: What commits to make? (#2) as I made smaller changes, I had trouble making my commit messages specific enough How would you describe these changes in a commit? If we look there are two changes - font color and underline - but what could you say to give yourself a mental picture of the images? I started saying “rm lighter green font & add underline to nav bar” but with all the greens on the site, I started to think maybe should say “rm lighter / brighter font &...” my commits got longer and longer and I thought I was doing a good job but when I went needed to actually view my changes, I had all these long descriptions that had me wondering if it was the lighter green I wanted or the really light green. That, and my Git history was messy and hard to navigate - I had to manually “rollback” to several points just to find the version that I needed when I had made a mistake. Where was I to go from there? What other cues could I give myself?
6. Slide 6:: What commits to make? (#2) as I made smaller changes, I had trouble making my commit messages specific enough How would you describe these changes in a commit? If we look there are two changes - font color and underline - but what could you say to give yourself a mental picture of the images? I started saying “rm lighter green font & add underline to nav bar” but with all the greens on the site, I started to think maybe should say “rm lighter / brighter font &...” my commits got longer and longer and I thought I was doing a good job but when I went needed to actually view my changes, I had all these long descriptions that had me wondering if it was the lighter green I wanted or the really light green. That, and my Git history was messy and hard to navigate - I had to manually “rollback” to several points just to find the version that I needed when I had made a mistake. Where was I to go from there? What other cues could I give myself?
7. So there were a few things I could try: Use the tools I had better, find other tools that gave my visual brain the cues I needed, or… I brainstormed about this for some time. To address the problem, our design friends would tell us, we need to define the problem...
8. The difficulty was that I didn’t know how far back I would be going. Look at all those steps! Understand that as a visual person (& others experimenting with back-and-forth visual work may have the same experience), I was mentally recreating the image in my brain from commit messages. The loop of going back and maybe to the wrong place for frustrating for me and took me outside of a productive flow. I was ready to smooth this part of my workflow.
9. Without the framework that design offers, I put on my problem-solving engineer hat looked for ways to make it easier to “preview” without rolling back and came up with a few solutions: I was already keeping screenshots to show to clients, so it seemed natural to keep my own folder of screenshots. Sometimes I would flip though like a flipbook to look for trends that might infom where I should go next but when I was looking for a specific image (like “I need the 4-link nav bar, no underlines”), I still struggled looking through timestamps or tiny icons - I realized I needed these images to be *connected* to my version control to do me any good. Meanwhile, I had learned about in-editor hex-color previews (some even let you select/add with a UI). These helped when I was coding but to open “rolled-back code” in my editor I would have already needed to do that git checkout dance and messing up my flow. I started thinking about a programmatic solution.
10. Next step was to save a screenshot in Git, linked in the commit message to you could click and see what the page had looked like at that commit What pain points remained? Time spent taking screenshot by hand Might forget to add screenshot / add wrong one and back at that giant folder of screenshots Time spent renaming and linking Time spent wondering how often to take screenshots since it was a pain - made worse because starting to worry about wasted time How to address? Had used all the tools I could - like an engineer I had put them together to solve a problem in a creative way but I made new problems too - maybe I didn’t know what problem to solve? Started talking to other developers about my idea - and people disagreed A LOT, such strong reactions told me I should be looking into this more Usually those working at agencies said “we don’t have time for that kind of documentation”, individual contractors (me!) were excited, and folks at large companies said “oh we have that”. Developers from large companies had something to say: Screenshot diffing, used by… almost every large company I spoke to (eBay, Google, etc.) compares screenshots as part of their testing process
11. Screenshot diffing explanation Compared to “golden” and kicked back if above a certain % different - a human can correct or set as the new golden Note: I would not have known to ask if I hadn’t gone beyond using the tools and experiences I know (asking folks working in different settings) As I thought about the visual aspects of the problem more (and had my decision reinforced by success talking to folks within industry), I realized (just like a number of devs!) there was a group of folks I *wasn’t* talking to: Designers!
12. The thing that surprised me the most about discussing this idea with design folks is how quickly they pointed me to tools that they used and the curiosity they had about Git and other tools used by developers. We heard earlier how powerful it can be for a design person to use developer tools and how inaccessible it can seem and my interviews really back up the previous speaker’s experience - we’re working so closely - sometimes just desks away from our designer-teammates - but often don’t understand what they are doing, how they are doing it, or what we can learn from each other. In all cases, my designer-chats were extremely eye opening - if you haven’t already, I encourage you to “talk shop” with someone who works on a different aspect of your project - you might be surprised at what you learn. So don’t be this cat, he’s not having any fun and he’s not learning anything new
13. In my case, I learned that designers had already solved my problem Sketch’s “pages” similar to my folder I had started out flipping through - so validating! Abstract’s “compare mode” is a “Git” for sketch (prototyping) files - right down to the commands and the timeline visualization Designers had been wanting a “Git” for their visual work the same way I wanted visuals to support my code-based work. I repeat: Designers have a “Git”! I set out to see if I could “git” some visuals more smoothly into my workflow. Sources: Abstract image: https://www.goabstract.com/blog/compare-mode/ Zeplin image: https://twitter.com/zeplin/status/790945731339182080
14. Our steps so far: Made a prototype, saw it’s problems, confirmed problems were common, researched how others solved related problems (lay of the land), What are our pain points? Time to take screenshots -> Screen diffing means Puppeteer / Pyppeteer (etc) support this Remembering to take screenshots -> Use a “Git Hook” (script that makes other things happen when you take an action within Git) so in this case, when we commit within Git, Git will turn and “tap” Pyppeteer and let them know it is time to take the screenshot. Adding image link to your commit message -> Still working on this part - any ideas? I believe that I could make a script that tests for the new file and a terminal prompt to ask if I’d like to add it… We can think of each of these steps as a wrapper (sets in motion other steps) of the steps that it is calling.
15. One part of this exploration for me has been realizing the value my experiences (both as a geologist and a visual learner) can bring to my work. That’s a hard realization to come to because, as I started to transition careers, many folks could not hide their shock - “a geologist?! *that’s* a shift!” Similarly, when I started to explore screenshots in Git, I heard a strong “we don’t do that”. This is rough stuff for people to hear and I felt as I was working toward my first job that I would need to put “my last life” behind me so I could be successful in this one. The shame of that is that I was most able to contribute when I realized the value of my past. This affects a lot of people: As I was writing this talk, I got a twitter message from a career-shifting academic thanking me for talking openly about my research life. He went on to say how much it meant for him to have me talk about that openly. Being able to use our pasts and all our skills is powerful and will make us better programmers & people. Should you be using screenshots in your version control? I don’t have an answer for you. The nearly 50/50 love it/hate it split I encountered does indicate that it’s an idea worth chewing on - and I can’t help but notice that roughly 65% of humans are visual learners - maybe that accounts for some of the 50% who gave me big “yes please!” If you are looking for a new way to support a more diverse group contributors or teammates, consider pushing back a little on “we don’t do that” and exploring new options.
16. Here are some tools I used that you may found helpful. No Q’s but I’d love to talk about this more - tweet me. Wanted to thank you all for being such a lovely audience - I’ve never spoken in front of more than 20 people before and I don’t know if you’ve noticed but there are A LOT of you so I really appreciate the support. I’ll be speaking twice more this month so if you give me a follow you’ll be able to join in on my git-venture. Working on another talk about in-code comments and would love to hear how you use them.