Guide contents planning about git-guide HOT 3 OPEN

Hey Chuan Hao! Really glad that you're looking to help out again on this guide! 😄

Priority work

While I really like those chapter ideas (I think having an understanding of git diff would be very useful for students when collaborating with one another), I think we should tackle the core content that was originally planned. And that would be the chapter on branches on Git (https://woojiahao.github.io/git-guide/06-branching/).

This would give a better foundation for readers when going into more advanced topics as these advanced concepts use the idea of branches quite heavily so explaining how branching works is incredibly useful.

I would say that the important idea behind branches is perhaps trying to illustrate how the Git history works. I'd personally try to link the idea of the branches with an actual tree and build on that analogy.

Tips & Tricks

As for the "Tips & Tricks section", I like the idea a lot 👍🏻 I think we could create a new chapter for it (so that they're all housed under the same folder or something to create sub-chapters if each get too long). However, I'd say that ideally, these should be short snippets, rather than lengthy explanations. If we want to explain each concept in depth, perhaps that would warrant its own chapter but that would be decided when we actually start writing the chapter out.

Backlog of tasks

Apart from that, I do have a backlog of tasks that would be a good "quality of life" improvement for the guide. I will have to add them in as issues/cards in the project backlog but I'll list them here so I don't forget about them too:

• Implement SEO for the guide on Gatsby.js
• Add a mini-summary section after each chapter that captures the key commands taught and their use case in brief
• Migrate the practical section into the main site
• Complete Git branches chapter
• Add more content to the "Advanced Git" chapters like git diff, git blame, git fetch && git merge vs git pull, how Git works under the hood (could be a completely separate chapter)

from git-guide.

Priority work

This would give a better foundation for readers when going into more advanced topics as these advanced concepts use the idea of branches quite heavily so explaining how branching works is incredibly useful.

Yup, I agree with doing the branches chapter first.
Although my concern is that with branches, we would probably need to touch on things like the staging area, refs pointers and deeper git concepts. So I was wondering if this might confuse people with the advanced-git chapter. (Would like your thoughts on this)

I think I will start work on this, although I would expect to have quite a lot of drafting to be done. :D

Tips & Tricks

As for the "Tips & Tricks section", I like the idea a lot 👍🏻 I think we could create a new chapter for it (so that they're all housed under the same folder or something to create sub-chapters if each get too long). However, I'd say that ideally, these should be short snippets, rather than lengthy explanations. If we want to explain each concept in depth, perhaps that would warrant its own chapter but that would be decided when we actually start writing the chapter out.

Yup, agree with this too. Although my idea was more on showcasing what tips and tricks can be done in a sub-chapter. Then we would provide them mainly with the references. (Could also be a good idea for people to collab and contribute on this :D).

I would prob start a draft with this soon as well :D.

Backlog of tasks

I don't think I have anything to add here. I will just play by ear.

Closing

Thanks for the fast response. Was busy with work yesterday so I could not reply. Happy to work on this again XD.

from git-guide.

Although my concern is that with branches, we would probably need to touch on things like the staging area, refs pointers and deeper git concepts. So I was wondering if this might confuse people with the advanced-git chapter. (Would like your thoughts on this)

I don't think we need to get into so much detail right off the bat. We can park the slightly more advanced aspects of branches in the advanced Git section. Alternatively, I can also see the following format working:

1. Introduction to branches in Git (high-level overview)
2. How does branches work? (link to DAGs) - briefly explain the idea
3. How does branches work? - in depth

So rather than focusing on explaining everything at once, ease them into the more challenging topics

from git-guide.