5 ms·

The giant font doesn't make it any easier to understand. Stuff like 'your local repository consists of three "trees" maintained by git' only makes sense to peop

The giant font doesn't make it any easier to understand. Stuff like 'your local repository consists of three "trees" maintained by git' only makes sense to people who already know how git works.

pixeldude 15y ago
I'm always happy about better wording. Any ideas?
- spacemanaki 15y ago
  I think the problem is that the guide doesn't explain the vocabulary it uses at all. There are programmers (and definitely non-programmers) who might not have heard the word "tree" used to describe a directory filled with files and other directories. It's immediately clear once it's explained, and the guide even has little drawings that look like a directory tree, but for people new to version control and people who have used CVS or SVN this use of the word might be foreign. The same with "commit" since someone coming from another system has a different idea of what that means and someone new to version control has no idea. Honestly, I'm not even sure you need to talk about "trees". The first chapter of Pro Git doesn't mention them at all, and this section describes the working dir, the index and HEAD without using the word: http://progit.org/book/ch1-3.html http://progit.org/book/ch1-3.html Instead he talks about "snapshots" and "stages".
  - pixeldude 15y ago
    I found it pretty helpful with the use of the word "tree" (got it from http://progit.org/ http://progit.org/). But I definitely need to add some kind of glossary to the page.
dpcan 15y ago
Exactly. You can use a big happy font, but when step 2 tells me to create a "repository" and I'm already stuck.... well, that's a problem. A repository for what? Is this a folder on my computer somewhere? Should I be moving code into this folder? No idea. In order to make this tutorial helpful, why not take a simple project and get it working under Git? For example, let's say right now I have a folder that consists of a single source code file like testapp.php, a README.txt, and then a content folder with some images in it. How can I take this mini project and start using Git to manage my code? I'm seriously that "beginner" when it comes to Git. I do not understand it at all. Maybe I'm not your audience. This tutorial was FAR from simple IMO.

The giant font doesn't make it any easier to understand. Stuff like 'your local repository consists of three "trees" maintained by git' only makes sense to people who already know how git works.

pixeldude 15y ago

I'm always happy about better wording. Any ideas?

spacemanaki 15y ago
I think the problem is that the guide doesn't explain the vocabulary it uses at all. There are programmers (and definitely non-programmers) who might not have heard the word "tree" used to describe a directory filled with files and other directories. It's immediately clear once it's explained, and the guide even has little drawings that look like a directory tree, but for people new to version control and people who have used CVS or SVN this use of the word might be foreign. The same with "commit" since someone coming from another system has a different idea of what that means and someone new to version control has no idea. Honestly, I'm not even sure you need to talk about "trees". The first chapter of Pro Git doesn't mention them at all, and this section describes the working dir, the index and HEAD without using the word: http://progit.org/book/ch1-3.html http://progit.org/book/ch1-3.html Instead he talks about "snapshots" and "stages".
- pixeldude 15y ago
  I found it pretty helpful with the use of the word "tree" (got it from http://progit.org/ http://progit.org/). But I definitely need to add some kind of glossary to the page.

dpcan 15y ago

Exactly. You can use a big happy font, but when step 2 tells me to create a "repository" and I'm already stuck.... well, that's a problem. A repository for what? Is this a folder on my computer somewhere? Should I be moving code into this folder? No idea. In order to make this tutorial helpful, why not take a simple project and get it working under Git? For example, let's say right now I have a folder that consists of a single source code file like testapp.php, a README.txt, and then a content folder with some images in it. How can I take this mini project and start using Git to manage my code? I'm seriously that "beginner" when it comes to Git. I do not understand it at all. Maybe I'm not your audience. This tutorial was FAR from simple IMO.