dwyl jargon buster

[hdrdavies]

An issue for discussing repo / Github terminology and how to explain them in the most intuitive way.

I like the explanations given in this article for the following:

Repository A directory or storage space where your projects can live. Sometimes GitHub users shorten this to “repo.” It can be local to a folder on your computer, or it can be a storage space on GitHub or another online host. You can keep code files, text files, image files, you name it, inside a repository.

Commit This is the command that gives Git its power. When you commit, you are taking a “snapshot” of your repository at that point in time, giving you a checkpoint to which you can reevaluate or restore your project to any previous state.

Branch How do multiple people work on a project at the same time without Git getting them confused? Usually, they “branch off” of the main project with their own versions full of changes they themselves have made. After they’re done, it’s time to “merge” that branch back with the “master,” the main directory of the project.

I also like the way this guide has concisely defined an..

Organisation A GitHub organization represents a group of people working together, like a company or an open-source project.

@iteles I like the way organisation is explained above, rather than saying that an organisation is similar to a 'folder' to keep projects in, as this might seem too close to a definition of a repo. Non-technical people might think "Well, what's the difference then?"

[iteles]

@hdrdavies A fan of the organisation definition, good find :+1: I would replace 'open source project' with 'collaborative project' because I find a lot of non-technical people don't yet understand the term open source (and we don't want to get distracted with teaching them in this repo.

Arguably, commits but especially branches may be too much for this particular repo given this is something that the audience won't really interact with (maybe commits at the issue referencing level...).

If you use these, please remember to add a note of thanks to GitHub Education at the bottom of the repo in <small></small> for example :blush: :+1:

[hdrdavies]

@iteles oh noes! I added the commits and branches definitions. I'll push them up for review and happily take them down if you feel they're too much for this guide. Will add thanks to GH education and readwrite for their help

[iteles]

I did say arguably, so feel free to argue ;)

[hdrdavies]

@iteles :wink:

It's a tricky one. I feel that they may be a touch too technical, but I also feel it's fair to give clients an explanation of words they might come across. I feel that they're likely to be curious and would like to know some of the terminology.

To avoid any sense to being overwhelmed though, we could add a preface to the Terminology paragraph saying "Don't worry about fully understanding these development concepts, we've provided them in case you're curious as to what they mean!"

[iteles]

:+1:

[hdrdavies]

A not too technical definition of a sprint.

[rebeccaradding]

@iteles @hdrdavies as a "non-technical" person who's learning how to contribute to work on GitHub, I'd suggest linking to the "Hello World" exercise at the end of this document - and perhaps adding a few notes about naming conventions, as I got tripped up the first time I created a new branch not knowing what I was expected to call it.

[iteles]

@rebeccaradding Do you mean a new branch (as in something you're actually adding files and code to) or a new issue? Or even a new repo? (just to be clear so we can help with what you need - thank you so much for raising the issue!)

[rebeccaradding]

@iteles I mean a new branch. Hello World walks you through the process of branching and merging but does so using a repo and read-me that you're the only contributor to. When I was faced with creating a branch so I could update a README on our website, I wasn't sure what to call the branch to keep things consistent with what people had already done. Does that make sense?

[iteles]

@rebeccaradding Makes total sense! Thank you so much for this.

Feel free to PR this is if you have some time when you're back from your honeymoon and no one has got to it first :wink: