Git hooked on images and up your documentation game

1. Git “hook[ed]” on images and up your documentation game @veronica_hanus @PyCaribbean
2. @veronica_hanus @PyCaribbean Creative documentation
3. @veronica_hanus @PyCaribbean View changes remotely, feel amazing and... Push ASAP Commit Make changes to code locally My first year learning to use Git Veronica’s early Git workflow A more thorough daily flow: - Pull other’s changes - Create branch / checkout branch - Local changes - Commit - Push when element is done - Check status - Continue local changes - (eventually) Merge branch You may also: - Undo commits - Squash commits - Undo push - Fetch - Rebase
4. A timeline of a Very Visual Veronica Always: “Documentation Lowers Cognitive Load” Geology Web Workflows for ML ? (what next?) @veronica_hanus @PyCaribbean
5. Iteration is not design! What does a design process look like? - Team “interview” - Translate business objectives to new state - ID what you don’t know - Review existing market product - Brainstorming - Listing user tasks - Roadmap - Focus group - Card sorting - Usability test - Concept testing - Guerrilla testing - Field studies - Eye movement tracking - Accessibility audit - A/B testing - (finally) Iteration Design has methods & tools! @veronica_hanus @PyCaribbean
6. Challenges of Git’s “time travel” w/ commits “Picture perfect” commitsComment fatigue - Summarize in subject (“what”), expand in body (“why”) - Avoid abbreviations - Use metadata (Issue IDs, etc.) - The test: “If applied, this commit will *subject line*” - Make Git log useful! @veronica_hanus @PyCaribbean
7. - “Remove lighter green font & add underline to nav bar” - “Remove lighter/brighter font &...” What commit message should we make? So many greens! Long and still hard to understand! @veronica_hanus @PyCaribbean
8. What would you do? Better commit messages? Find tools giving cues? Other ways? Your idea here @veronica_hanus @PyCaribbean
9. Steps to roll back to a commit: - Select the commit - Find the ID for the commit - Enter command to “checkout” the commit with that ID - Open the code & HTML file - Is it what we want? - Create new branch (section of timeline) before making changes Rolling back individual commits @veronica_hanus @PyCaribbean
10. Screenshots in a local folder One problem at a time Color preview in-editor @veronica_hanus @PyCaribbean
11. Screenshots in saved in Git Moving toward a solution What pain points does my solution have? How do I address these? @veronica_hanus @PyCaribbean
12. Screenshots for testing… and tracking? A few tools: ➔ Puppeteer-screenshot-tester ➔ Resemble.js ➔ Wraith Screenshot diffing @veronica_hanus @PyCaribbean
13. @veronica_hanus @PyCaribbean
14. A “Git” for design! Our examples: Abstract’s Compare Mode, Sketch’s Pages & Artboards, Sketch’s Zeplin @veronica_hanus @PyCaribbean
15. Ready to dive in Puppeteer or Pyppeteer automate screenshots Git hooks “hook” one action to others Terminal prompt for you to save by hand Time to take screenshots Remembering to take screenshots Adding image link to your commit message Pain Investigate Your commit to Git Git hook calls Pyppeteer Pyppeteer takes screenshot Terminal prompts you to save @veronica_hanus @PyCaribbean
16. Bring yourself Geology Web Workflows for ML ? (what next?) @veronica_hanus @PyCaribbean
17. Keep in touch! @veronica_hanus @PyCaribbean Resources Thanks to… Each of you for coming(!), the PyCaribbean organizers for a wonderful event, my crew Kasey Wang, Deborah Hanus, Diego Berrocal, & Anna Ossowski for help investigating this topic ➔ Puppeteer/Selenium/WebDriver for screenshots taken at every change ➔ Abstract/Zeplin/Sketch for scroll- through visuals to be used alongside your version control ➔ Hand-created screenshots checked into version control ➔ Editor plugins that help you visualize the colors on your site ➔ Your knowledge of your process & workflow for deciding what is right for you Let’s talk about in-code comments! (3-5 min survey) http://bit.ly/comment-use
18. Credits - Git instructions for beginners: https://docs.google.com/document/d/1YZInGNW_YZQvTTsiOA1BkboveFzlez0TdlCjKIk4 UK0/edit?usp=sharing - Daily Git commands: https://gist.github.com/jedmao/5053440 - Commit XKCD: https://xkcd.com/1296/ - Good commit messages: https://chris.beams.io/posts/git-commit/ - Color preview in-editor: Sublime’s Color Highlighter (view), Atom’s Pigments (view) & Color Picker (select/add) - Source for screenshot diffing images: https://online-image-comparison.com/ - “Automated visual diffing with Puppeteer” (2018), Monica Dinculescue’s blog https://bit.ly/2C3z25t - Grumpy cat says “no new friends” https://makeameme.org/meme/no-new-friends-0lalol @veronica_hanus @PyCaribbean

Editor's Notes

Hello (And thank you for that)
I tend to ask a lot of questions, and I’d like to ask some questions from you all this morning. So if you hear me ask something, feel free to raise your hand our shout out.
Let’s start.
How many of you use Git and Github to track your programming files? (super) (respond to the response)
How many of you have explored different ways of documenting your projects? This could be with creative use of comments or man pages, images, anything.
This could be with creative use of comments or man pages, images, anything. Anyone experimenting to find their best documentation?
Maybe you want to…
ASCII to explain what your code does
Create whole man pages describing sections of your code
Maybe right now those “obvious” comments aren’t so obvious to you
The best docs is the use that helps you - you need to learn to solve the problems you have. The problem solving you do now will be with you throughout your careers - certainly longer than this year’s flavor of javascript! The best documentation won’t come without some mistakes.

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.
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. (CLICK) 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.
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! You see, I learn very well from visual cues. 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.
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. (CLICK)

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 sink in.
.
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.
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?
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?
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...
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.
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.
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
Screenshot diffing explanation
Compared to “golden” and kicked back if above a certain % different - a human can correct or set as the new golden

This was really exciting for someone who wanted to intgrate screenshots into their version control!
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 - making it much easier to keep asking), I realized (just like a number of devs!) there was a group of folks I *wasn’t* talking to: Designers!
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’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
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
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),

After my research I started to find solutions

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.
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. You may not be able to bring your whole selves to work just yet, but I encourage you to do it when you can. 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.
Here are some tools I used that you may found helpful. Even if you don’t get your questions answered today, I’d love to talk about this more - tweet me. Wanted to thank you all for being such a lovely audience - this is my second time giving this talk and this topic is exciting to me so I’d love to about it more. We do/don’t have time for questions. Also I working on another talk on documentation / in-code comments and would love to hear how you use them.

Git hooked on images and up your documentation game

You are reading a preview.

Check these out next

Git hooked on images and up your documentation game

More Related Content

Recently uploaded (20)

Featured (20)

Git hooked on images and up your documentation game

Editor's Notes

Git hooked on images and up your documentation game

You are reading a preview.

Git hooked on images and up your documentation game

Recommended

More Related Content

Recently uploaded (20)

Featured (20)

Git hooked on images and up your documentation game

Editor's Notes