Documentation for Push (was: Alternating between branches for contributions)

[brocktopus]

This issue is opened for anyone not that familiar with git/GitHub who might find him- or herself working on multiple types of contributions (article, blog, etc.).

You'll very likely want to swap into the master branch each time you generate a new branch to checkout so that the base is the master rather than whatever new branch you'd just made. Otherwise, you might find the 'predecessor' branch's commits follow you into the new branch. (See: my closed pull request here: #4 )

Example:
git checkout master
git checkout -b submission (this creates a new branch, 'submission', based on the master branch, which I'd previously been in)
-> make whatever commits desired in the submission branch
git checkout master (jumping back into the master branch to avoid my submission commits sticking with me when i make a new branch)
git checkout -b post (this creates a new branch, again based on master instead of submission)

[karlstolley]

I think we're going to need some more robust documentation...trying to decide whether gotchas & tips like this belong on the main site, or perhaps as a GitHub wiki associated with the Push repo. Thoughts?

[brocktopus]

Good question. I considered after opening this issue that it might be better served as a blog post (with maybe a 'help' tag or the like), but wasn't sure if that was really the optimal place for this sort of info. If a wiki would be the best home for it, then sure.

[lingeringcode]

As a person who is still very new to the GitHub discourse and workflow/methods, I would personally benefit from a more robust and localized documentation about/for the Push repo. I think accommodating to the newer folks to this level and type of workflow, (using git, that is), could help stimulate an inclusive environment. I'm thinking, in particular, for those of us in the subfield of C&W.

With that said, I think this type of info belongs on the main site in close proximity to the action associated with the help documentation. I think it should live there, and should eventually be available in video format as well, so people who are really new can at least situate and orient themselves to these VERY new processes, platforms, and, of course, the command line. Really, Push can create some great exigencies for lessons in documentation in tech comm courses.

Also, I think it'd be great to create a developing library/glossary of terms (master, branch, checkout, etc.) that could easily be highlighted and referenced on the Push site in similar ways akin to e-readers, because I think it's easy to get bogged down in jargon, even from the help.github pages.

Just some thoughts for the long run.

[zobelg]

As someone totally new to GitHub workflow, I agree with lingeringcode. There's a fair amount of learning and orientation needed to "get" GitHub. I don't know how open y'all are to livecoding or live screencasting, but it would be helpful to see video and hear think-aloud protocol while you do what you do to create content for Push. Written documentation is useful as a reference, but I learn more effectively from watching live action. GitHub tutorials exist, yes, but seeing you work in the context of creating Push would be optimal--for me at least--to learn.

I'd hope that these kinds of screencasts would not only benefit others, but they'd also be relatively easy to make since they're just documenting your work as your work instead of being separate pieces of content.

[karlstolley]

Completely in agreement on the need for more support materials for learning. And Greg's ideas of a Push-specific thing seems smart. I'll do a dry-run screencast for the blog post I'm writing tomorrow & post (prob. on YouTube...) and then improve it for a subsequent post, based on feedback.