Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Suggestion for improving the git staging area graphic #759

Open
unicrey opened this issue Sep 29, 2020 · 6 comments
Open

Suggestion for improving the git staging area graphic #759

unicrey opened this issue Sep 29, 2020 · 6 comments

Comments

@unicrey
Copy link

unicrey commented Sep 29, 2020

I am referring to the graphic http://swcarpentry.github.io/git-novice/fig/git-staging-area.svg found in the episode http://swcarpentry.github.io/git-novice/04-changes/index.html about halfway through the episode.

I think there is a dissonance between the metaphor used in the text and the graphic that goes with it. The text talks in terms of a photo capturing metaphor. git add is adding things to the frame of a snapshot and git commit actually takes the snapshot. I feel this is very intuitive. This is even carried forward with the idea of git commit -a being something like a group photo where any random person could appear.

On the other hand, the graphic shows documents on a cylinder as the staging area and the cylinder is then stacked atop other cylinders to represent the repository. While this is a fine graphic, I feel it does not go well with idea of a 'frame' from the text.

Instead, we could have something like a rectangular photo frame for the staging area and a stack of photographs to represent the repository. One or two documents would be shown within the frame and the top photograph and a couple of documents could be shown outside the frame.

Additionally, extending the photo capturing metaphor, .gitignore could be explained in later episodes as putting a filter on the lens so some files are invisible to the git frame.

@markmatney
Copy link
Contributor

markmatney commented Oct 10, 2020

I feel the dissonance as well. While I think it's valuable to have abstract conceptual models in the lesson (in case an instructor judges them appropriate for their workshop), I agree that the "Git as a photographer" analogy is compelling and should be developed more. Perhaps this can be a source of inspiration? 😄 (thanks to @jt14den for showing me that lesson)

And I like your idea of extending it to .gitignore. Although, instead of comparing it to a lens filter, what about: a request to not be recorded? ("Photographer, I'd prefer not to be filmed / please don't take my picture"). I like this better because it gives human subjects more agency and avoids questions about the construction/purpose of a hypothetical people-filter. "Out-of-frame by request", vs. "in-frame but edited/blocked out".

@unicrey
Copy link
Author

unicrey commented Oct 10, 2020

'git as a photographer' sounds good. That image you refer to is exactly the kind of thing I had in mind.

I hadn't thought of it that way regarding the filter. It's a very important point about the appropriate cultural context of our analogies.

@dojobo
Copy link

dojobo commented Nov 8, 2020

In a recent git workshop I used a "photo booth" metaphor--the camera only captures what is inside the booth (i.e., staged for commit). Things may be going on outside the booth that are not captured (untracked files, .gitignore). The "snapshots" (commits) are collected in an "album" which forms your git repo.

@markmatney
Copy link
Contributor

markmatney commented Nov 9, 2020

That's an interesting idea. Although, if the photo booth implements both "tracking" and "ignoring" (presumably with the boundary that it introduces to separate "inside" from "outside"), the distinction between the two operations seems to me a bit blurred w.r.t. the metaphor, and a potential point of confusion for learners. How did you maintain that distinction? Were there any follow-up questions?

@kekoziar
Copy link
Contributor

kekoziar commented Jul 23, 2021

The analogy and the image are two different ways of representing what's going on. The image doesn't need to reflect the analogy. When we teach it some learners will understand after we read the analogy, and some will understand when we show the image. The two examples are there because it allows different mental images to help different learners with the concept.

But, @unicrey the call-out in the middle of episode 4 is the only place the photo analogy is used, while the format of the image is used throughout the lesson. How would changing the image to what you propose impact the rest of the images in the lesson?

@markmatney
Copy link
Contributor

markmatney commented Aug 10, 2021

I think part of the "dissonance" feeling might be coming from the image being positioned directly after the "Staging Area" call-out box -- something about that (at least to me) is communicating that the two are meant to accompany each other.

To me, the text preceding the call-out box is a better lead-up to the image, so how about we move the image in question above that call-out box (and perhaps also put a colon at the end of "but not yet committed")?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants