WIP: Gitlab Introduction Slides

What needs to be done

• GitLab Git CheatSheet (printable)
• Git overview first
• GitLab overview second
• Some GitLab screenshots third

cc @nearlythere, @lukebabb, @JobV

@lukebabb Can I ask you for some help with a design here? We need to prepare a template for GitLab slide, it should also be printable (reveal.js supports print stylesheets) and we also need a table for GitLab Git CheatSheet. Thanks in advance!

@grzesiek happy to help out where I can. Do you have an outline of what you'd need from me? Also, what platform are you building the slides on?

@lukebabb We are using a reveal.js (like in diff for this MR). What is a most important at this moment is a design of GitLab Git CheatSheet (something similar to GitHub Git CheatSheet). Will will then need some help from @jschatz1 probably, to integrate this design with reveal.js framework, I will provide content.

@grzesiek ok great, checking out reveal.js and starting to make sense, sorry for the confusion earlier.

Link to GitHub Git CheatSheet: https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf

@grzesiek are you building this on http://slides.com/? If so, we may be able to build everything with their in-browser tools and may only need @jschatz1 to help if we're implementing super complex stuff.

@lukebabb Good catch, I somehow overlooked slides.com, thanks! I will check if this is enough for us.

@tmaczukin Since we both go to RailsGirls, can I ask you for a help with this MR? I'm running out of free capacity until 8.5 release.

@grzesiek Of course. What help do You need? :)

@tmaczukin We need a GitLab Git CheatSheet. Can you create it?

if you need any help lmk

Added 1 commit:

• b1fa1293 - Add GIT CheatSheet - page1 (draft)

Added 2 commits:

• 35f9e2f3 - Finish draft of GIT Cheat Sheet - page1
• cdc5dd71 - Add draft of GIT Cheat Sheet - page2

@nearlythere @lukebabb @grzesiek: I've created a draft of GIT CheatSheet. It's in SVG, but SVG files created in Inscape, which are using external fonts and lots of layers... it not looks good in the GitLab integrated SVG preview.

I've generated PDF from those SVG files. Where can I place it? I would like to ask You for a review. And for some help with overall design.

Added 1 commit:

• 90cbfb41 - Update draft of GIT CheatSheet - page2

@tmaczukin can you attached the PDF for review here on the issue? @grzesiek @nearlythere let me know how else I can be of assistance.

@lukebabb Sure: gcs-draft.pdf

@tmaczukin this is looking really great. A few design related suggestions:

• I'd make the purple bar that makes up the page footer about half as tall, the website and version text looks good.
• Right align, instead of left align, the number headings for each section.
• I know this is still a work in progress, but it would be nice if the text within the PDF version was selectable so users can copy and paste if needed.

@lukebabb Thanks for suggestions! :)

• I'd make the purple bar that makes up the page footer about half as tall (...)

With @grzesiek we want this cheet sheet to be printed. So a part of the site margins will be used as a printer margins (without any print on it), and a part will be removed by cutting it up. I suppose that in the printed version we will have ~5-8mm less for each page site.

After finish I can prepare a screen-only version of the PDF with smaller margins :)

• (...) but it would be nice if the text within the PDF version was selectable (...)

Like the above - for printing it is better to convert the text into curves. But for screen-only version it will definitely have a normal text and embedded font.

I should have a finished draft version today evening.

Added 1 commit:

• 34524864 - Update GIT CheatSheet drafts

Added 1 commit:

• 9c296d28 - Update GIT CheatSheet drafts

I've finished the draft of the GIT CheatSheet: gcs-draft.pdf.

@lukebabb, @nearlythere: Please do a design/marketing review. I think we can put something on the right side of the second page's footer.

@grzesiek: Please do a technical review.

@tmaczukin Amazing! It is great!

@tmaczukin oh my word it's so beautiful!

i'm so excited you get to test it with users. i am reading it now.

@tmaczukin

• Throughout: Change "GIT" to "Git"
• Section 1:
  • Shouldn't it be user.name and user.email (missing r)?
  • I might change the "[put your whatever here]" to use real examples so they don't think the brackets are part of it. "Your Name Here" and "you@example.com"
• Section 2
  • "... Git will create a new directory ..."
  • "... then a new repository ..."
• Section B
  • Why is this a letter and not a number?
  • The console output extends below the gray box
  • "All it will be ignored"?
• Section 3
  • "Day-to-day" (hyphenated)
  • Unbold "is" in "is unrecoverable"
  • Saying git stash pop clears the stash might be confusing. It only applies and removes the most recent stash. Fine to keep if you want to keep it simple and assume they only stash one thing at a time.
• Section A
  • Again, why a letter?
  • "... available in the standard system repository."
  • "An excellent Git course ..."
  • "online for free at https://...."
• Section 4
  • "Git will create the specified branch if it does not exist."
• Section 5
  • "List commits that are present ..." (plural, no comma)
• Section 6
  • I think mentioning GPG tag signing at all in a document like this might be a stretch
• Section 7
  • "discarted" -> "discarded"
  • "leaves a difference as uncommitted changes" - Not sure what we're trying to say here
  • "... reverting changes from the specified commit."
• Section C
  • Letter?
  • "Only remember to" -> "Just remember to"
  • Why a question mark after "Remote repository named origin"?
  • Unsure about the warning about doing backups
• Section D
  • Letter, etc.
  • Remove "you see it, right?"
  • "It looks as a developer's note" -> "It looks like a developer's note"
  • "parrents" -> "parents"
• Cloud
  • "an chaos" -> "chaos"
  • "a chaos" -> "chaos"
  • "no version control was made" -> "no version control was used"

Whew!

Git is not an acronym. Git (capital G) when referring to the programming language and git when referring to commands. Instead of GIT throughout.

I like the heading on the 2nd page, mainly because it also frees up space.

Typos

LOL as I wrote this, @rspeicher filled out most of them.

In 2 title

2. Starting a project

In 5 title

5. Review your work

In 8 title spelling:

8. Synchronising repositories

In the cloud:

"And this is the past. Here was chaos where no version control was used. Don't live in chaos! Use Git!

Under D.

This is a merge commit, it has two parents!

Footer - Capitalize E. Use the URL and same footer on both pages.

GitLab - Everyone can contribute http://about.gitlab.com

I love the look of the document! But as a digital asset it poses a challenge in that it's inaccessible to screen readers, as far as I can tell. There is also no way to search for text in the asset. I think for a v 2 we can make this in a different format, PDF?

Re: accessible SVG http://www.sitepoint.com/tips-accessible-svg/

Small line cut by background.

Section B. Why is this a letter and not a number?

Sections 1.-8. are about using the command line tools. Most of them (maybe except init/start) you are using every day.

Sections A.-B. are a sort of appendixes to this cheat sheet.

A describes installation and documentation link. It is something, that you are doing once per environment.

B describes files ignoring. It is something you are doing more or less frequently, but such cheat sheet is to small to wrote everything about this. But I think it's important that Git user knew about this, so I introduced it in the cheat sheet.

C and D are a description (very simplified description) how Git works under the hood. After 3-4 years of helping people with understanding Git I realized, that most of problems disappear when one understand the differences betwenn working area/index/repo/remote repo, and when one understand that a branch is a reference (pointer) to the commit.

Saying git stash pop clears the stash might be confusing. It only applies and removes the most recent stash. Fine to keep if you want to keep it simple and assume they only stash one thing at a time.

Yes, exactly. I know that this works only with the most recent element on the stash. But this is complicated for Git beginners even when they think that stash can hold only one change. So i will leave it as it is, for the simplicity.

I was saying this to all people I worked with: "You want to use Git properly? Read the manual or the Pro Git book. Then you will understand how this work and what features Git is giving you."

I think mentioning GPG tag signing at all in a document like this might be a stretch.

Yes, I think you are right. I wanted to signal, that Git provides a method to sign tags and commits. But that can be confusing for the beginners. I will remove all mentions about GPG/signing.

Why a question mark after "Remote repository named origin"?

Read it, like it would be a story which someone is telling You: "You are asking me why this repository is named origin? Well... You probably cloned the local repository from this one, and Git named it like that."

Unsure about the warning about doing backups

I wanted to make the cheat sheet a little bit funny. Myself I like such materials. Two pages with only raw tips... it's good, but it's boring.

But if anyone think that this is not a place for this, then no problem, I can remove it.

Remove "you see it, right?"

Like the previous one.

I love the look of the document! But as a digital asset it poses a challenge in that it's inaccessible to screen readers, as far as I can tell. There is also no way to search for text in the asset. I think for a v 2 we can make this in a different format, PDF?

Like I wrote it earlier in this MR - this is a draft and the PDF is prepared for be printed. When it will be finished I will prepare two versions - one for printing and one for on-screen use. The second one will have a normal text and embedded font.

@nearlythere @rspeicher: thanks for pointing all the typos and for the other comments! The fixes are on the way!

@rspeicher: I've missed this:

"leaves a difference as uncommitted changes" - Not sure what we're trying to say here

Lets say, you have a branch fix/a which is ahead of origin/fix/a with two commits. The diff between fix/a and origin/fix/a show some changes.

If you do git reset --hard origin/fix/a, then your fix/a branch will go back to the commit referenced by origin/fix/a and your working directory will be clean.

If you do git reset origin/fix/a, then your fix/a branch will go back to the commit referenced by origin/fix/a (like previous), but your local directory will have changes - exactly the same that you've checked earlier by git diff origin/fix/a...

Those changes are not added to the index.

In my opinion this is important to know the difference between git reset and git reset --hard. I was using it many times in both ways. How can we describe it then? I'm not sure if you are pointing some lexical mistakes or maybe the whole line is confusing.

Fixed version: gcs-draft.pdf

Added 1 commit:

• 8f2a99c1 - Add fixes to Git Cheat Sheet

I'm not sure if it's just me but all of the text on the second page looks blurry compared to the first page:

And the tagline/url on the second page is in italics, but on the first page it's normal.

Re: Lettered sections. Ok. But it's kind of odd that you seem to want us to read top-to-bottom, left-to-right (Section 1 above Section 2), but then in that case you read Section B before Section A.

On my computer the text is same sharp on both pages. @nearlythere, @grzesiek - can you check how it looks at your computers?

I've fixed tagline/url - on both pages it's now in italics.

Ok. But it's kind of odd that you seem to want us to read top-to-bottom, left-to-right (Section 1 above Section 2), but then in that case you read Section B before Section A.

I think it would be odd if this were a book or an article. But this is a cheat sheet - you don't read it like a book, but search for a snippet you need at the moment.

Sections are placed like that to fit best to the layouts. Thats why B is "before" A - there is no enough place to replace them. And logically installation/documentation (A) is something that you need to now before you go with files ignoring (B). That's also why sections 5-8 on the second page are placed clockwise and not top-to-bottom, left-to-right. It's about fitting all of this on two pages A4 with margins, that are required for printing.

Newest draft: gcs-draft.pdf

@tmaczukin I'm still seeing the blurry text on the second page with the latest draft. Hopefully I'm not going crazy. Edit: It looks fine when I open it in Chrome. In the OS X preview app it's blurry.

Also the *.swp text is falling below the gray box in Section B again on this draft.

FYI - We're working on a GitLab Introduction presentation - Open to comments publicly, editable by all in GitLab (I can't edit the MR description)

https://docs.google.com/presentation/d/1y4gqgqX6cNgaPF6HTsAHidsSpHGnjURdMyNZcM62-oQ/edit

Added 1 commit:

• fb098a87 - Add some fixes

We have sent this version for printing: gcs-draft.pdf

After next weekend we should have a feedback from users who will use a physical version of this cheat sheet. Then we can improve it

@tmaczukin I was thinking of getting this over to Luke to work up in a different tool - so we can have an accessible file?

I'd like to promote this and make it downloadable in April!

mentioned in issue gitlab-com/marketing#7 (closed)

@nearlythere: I see that you've created an issue in marketing project. So let's move discussion about cheat sheet there. I have one fix to the content to add. And also some observations after first part that was printed. I'll write them in gitlab-com/marketing#7 (closed) later.

Added 1 commit:

• bff60b98 - Add information about '-m' in commit command

Marked the task GitLab Git CheatSheet (printable) as completed

We prepared slides in Google Docs, because we didn't have enough time to do this using reveal.js.

@tmaczukin can you please rebase leaving only Git CheatSheet related commits or pick those into a separate branch/merge request?

@tmaczukin Probably the latter solution would be better, so I'm closing this MR for now.

Status changed to closed

/cc @tmaczukin

@grzesiek I'm not sure if this is necessary since this MR is closed and for cheat sheet there is a related issue in marketing project: gitlab-com/marketing#7 (closed). Also in this MR we have the discussion about content in the cheat sheet. I would leave it as it is.

@tmaczukin That is great we have this in a marketing issue, but this is not merged anywhere.