Jekyll and GitHub Pages Tutorial

[fredgibbs]

This ticket will host review comments for this lesson (URL TBD)

[amandavisconti]

Edit: This is for the lesson at https://programminghistorian.github.io/ph-submissions/lessons/building-static-sites-with-jekyll-github-pages.

I merged a pull request that contains my ready-for-review lesson and a bunch of included image files at https://github.com/programminghistorian/ph-submissions/pull/5.

[fredgibbs]

OK! Here are some comments from a first pass at your excellent lesson. Some of these suggestions are not as articulate as they could be; please ask for clarification if needed! Generally, the comments are sequential with my read-through of the tutorial with an overview comment at the end. No suggestions below are absolutely mandatory as far as I'm concerned, and most are minor. If you disagree with anything below, which is inevitable, we can see if it anyone else flags it or specifically ask for more feedback on it. But this is what came to mind, anyway. I hope it helps!

In trying to keep in accordance with other lessons, we could use a better indicator of required (and perhaps preferred) skills and difficulty at the very beginning. There could even be a bit more on selling the virtues of having a static personal website (even when without much technical skill) rather than rely on generic templates and platforms, and be able to fully share and manage your own content easily over time. I know you get into this a bit later, too, but that could be a big selling point.

"Dynamic sites (e.g. Drupal or WordPress)" might be better as: "Dynamic sites, such as those created and managed by a content management system such as Drupal or WordPress,"

The GitHub & GitHub Pages section shouldn't separate the reasons for using a static site from the explanation of static sites. (so maybe put it after that, or even later in the tutorial when relevant). Also, I would reverse the order of the paragraphs, first explaining GitHub's relevance to static sites, then explaining the relation to git (which is probably less familiar or interesting to most readers).

The heading "reasons for using a static site (like Jekyll)" is a bit confusing (because Jekyll isn't a static site). Perhaps "(such as those made by Jekyll)"... However, I don't think there has been a clear explanation that Jekyll is software, like WordPress, that helps you make websites. That could easily be in the Jekyll paragraph in the static vs. dynamic section. It might be worth stating that explicitly, even though that's implied.

As for the advantages, I would emphasize maintenance and preservation (obviously related) as key virtues first, and ahead of spped and security since the former are likely more appealing to a general audience. In fact, the first point, though labled security and speed is also about having less maintenance hassle, so perhaps those points could be split apart (and my preference is to foreground the convenience ahead of the security).

The versioning advantage should be a separate point, because it's quite significant and in fact separate from free hosting conceptually. I think the customization point could be separated as well, building on what you have explained earlier (it's really hard to customize a WordPress theme, regardless of hosting).

I think the point about getting locked out of features, although I think I know what you mean, doesn't seem to apply here, since these complex CMSs can't be hosted at GitHub Pages (and can also do more than GitHub Pages in their own way). Your more important point is that you can build your website however you want and not rely on what hosting services do for you--but that of course takes considerable technical skill that isn't required by most hosting services (and the reason so many people use them, obviously).

The customization point could also make the point that it makes it easier to learn about building webpages and sites (and foundational techs like HTML and CSS) when you aren't fighting complex hosting software like CMSs. It's also easier to store resources like syllabi and publications and other stuff that you might want to have online but don't need a bloated control panel to manage (which they aren't good at anyway).

All this is to say that I think there's a lot to unpack in this early section on static site advantages that I think would be very helpful for readers (regardless of technical skill and if they are prepared to work through the whole tutorial).

More broadly, I think one issue giving me pause here is that the tutorial doesn't clearly delineate--at least to this point--the advantages of using static sites (and GitHub Pages) in general (which can be done entirely without installing a local version), from creating your own local Jekyll instance (which is obviously what the tutorial is for). Some additional clarification about the relationship between the technologies could help with this. Obviously the point is that there is great power in combining them, but I think that should be spelled out more plainly (clearly the sentiment is baked into the tutorial).

I think it would be helpful if the "Preparing for installation" section opened with a more high-level overview of what the general procedure will be and what the components are. Throughout the tutorial, the explanations of how to do things (the precise steps) are really clear and straightforward. Now that that part of the tutorial is so well done, I think the broader descriptions (often in italics after headings) could be expanded to say what has been accomplished so far and an overview of the steps in that section.

Considering the very nice introduction to the command line, the sections throughout the "Installing dependencies" section seems considerably more opaque. I understand that you have no interest in the nitty gritty here, and I agree. However, I think it would be useful to explain (given what seems to be the target audience) that readers don't need to understand exactly what the various component technologies are or what the commands are doing. But a bit more explanation at a high level of what the components are (Xcode, Ruby, etc) could add a lot of value here (and maybe more links of trusted resources to learn more), even if just to provide broad familiarity. The explanation for Jekyll seems especially terse, given that it's whole point of the tutorial (that is: it's a bit anticlimactic!). In my experience, people can be a bit perturbed about installing totally unfamiliar software on their computer--perhaps a sentence about the standard and trusted nature of these external pieces might assuage some fears about that.

The instructions for "Setting up Jekyll" seem to start a bit abruptly with a connection to GitHub that could be fleshed out a bit more. Also, "We'll now create a folder full of the files needed to run your website" could be confusing, since "the files needed run your website" could be confused with the Jekyll install (and dependencies) itself. Mostly what you set up is the website itself.

It would be nice to walk the reader through the files that are created. --Oh, I see that explanation comes after the site is running. I'm torn about where is better; at least we should have a sentence here that says an explanation is coming later if we preserve the present structure.

The "gem install bundler" line seems to come out of nowhere. More explanation would be helpful (and a brief note why this wasn't done with the other command line setup stuff in the previous section).

NOTE: All these nitpicky things are really minor! But I think that since the target audience is not familiar with most if any of these technologies, a little extra hand-holding goes a long way towards increasing comfort level. Not having enough explanation can imply (though I know you don't mean to) that the user should already know what's happening or what these things are. Clearly, you do this very well in some cases; I suspect that the few places I'm highlighting simply got overlooked given the length and complexity of the lesson. This is the problem with most Jekyll tutorials in my opinion, and perhaps a reason you've written this one. Some of the explanations on the "Run Jekyll on Windows" site you linked to has very good succinct descriptions that are worth considering.

In point 6: you might also mentioning that dragging and dropping the file onto a text editor in the dock works, too,since that can be faster than the menus.

More broadly, can we have a bit more on what a Gemfile is? (and if the reader needs to care about it beyond this particular step?)

For step 9: great explanation of the command string. Could we also have an overview statement / explanation of how the next few steps create a webserver on the readers' computer? I mean, that's a really cool thing that most people don't know is easily possible. I think we could play that up a bit more, as it is really the culmination of all these installation steps. In fact, starting at step 9 could be another section ("running your own webserver" or whatever), since that command is one people will run often (as opposed to the install steps).

The config.yml file doesn't seem to have any kind of explanation associated with it. It might be work explaining what the "" means and what .yml means (even if you touch on these more later). Again, this is jsut trying to demystify some of the weird-looking stuff that can seem off-putting to readers out of their comfort zone.

"This section will describe what you’ll be using to write blog posts and pages on your website (Markdown)," I find this terribly confusing: How about "This section will describe how to create pages and blog posts on your website"?

It might be better to explain pages first, rather than posts, because they are more straightforward, and that would make the difference of a post (vs page) easier to highlight (since they end up being a page ultimately) when explaining posts themselves.

The "Hosting in GitHub Pages" section could use an expanded introduction that explains how the section uses the GitHub app to mediate the transfer of files on your computer (particuarlly the Jekyll files) with your GitHub account. Again, just a bit more higher-level explanation before the step by step.

One aspect that might be useful to add at some point is a general note about troubleshooting. Obviously you can't anticipate every error, but there are two approaches worth considering and discussing here: 1) encourage people to open tickets when they hit a roadblock. This could help identify place where a small clarification or extra advice in the tutorial would be super helpful (not that you'd be responsible for monitoring or adding these); 2) Provide some strategies for trying to solve your own problem (googling for error messages, etc). There are lots of other tutorials on Jekyll, and people might find exactly the instructions they need to get back on track.

On the whole, this is really fantastic. Although of course I found a few sticky points (for me anyway), the explanation of the actual steps needed to be done is super clear (although as I've said, sometimes the motivation could be fleshed out a bit). It's only natural that in such a long tutorial a few paragraphs here or there could use a bit more polish. I think with tiny bit of revision, and after getting outside readers to share their thoughts, this could easily become the standard tutorial on using Jekyll for people learning to use these various technologies.

[amandavisconti]

Thank you, @fredgibbs! I really appreciate your thoroughness, and I agree that these are all things I'd like to improve. Will update when these changes have been made, and will try to make them within the next two weeks.

I'll continue soliciting user feedback; beyond that, what is the Programming Historian norm for "getting outside readers to share their thoughts"?

[fredgibbs]

You're most welcome, and I look forward to your edits (which you've already started, I see)!

Below is our review ticket template--perhaps a bit overly formal at this point, but we're trying to standardize and clarify our review process. I won't solicit any formal reviews until your changes are complete (although anyone could make a suggestion in the interim). If anyone comes immediately to mind, please let me know of anyone who you think would be a good reviewer.

The Programming Historian has received the a new tutorial: Building a static website with Jekyll and GitHub Pages by @amandavisconti. This lesson is now under review and can be read at:

http://programminghistorian.github.io/ph-submissions/lessons/building-static-sites-with-jekyll-github-pages

I will act as editor for the review process. My role is to solicit two reviews and to manage the discussion, which will take the form of comments on this ticket. We aim to complete this process within 4 weeks.

Members of the wider community are also invited to offer constructive feedback also on this discussion thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below).

The Programming Historian embraces openness in its review process, and endeavors to keep the review conversation here on GitHub. If anyone feels the need to discuss anything privately, you are welcome to email me. You can always turn to @ianmilligan1 or @miriamposner if you feel there's a need for an ombudsperson to step in.

Anti-Harassment Policy _

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutize ideas, to ask questions, make suggestions, or to requests for clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. If anyone witnesses or feels they have been the victim of the above described activity, please contact our ombudspersons (Ian Milligan or Miriam Posner - http://programminghistorian.org/project-team). Thank you for helping us to create a safe space.

_

[amandavisconti]

Paige Morgan responded to my tweet seeking lesson reviewers for within the next month. I'll follow up with her via email.

[fredgibbs]

Excellent! You can point her to the directions above (the reviewer-guidelines page contains the official directions) and/or have her get in touch with me directly. Thanks!

[amandavisconti]

In addition to making Fred's suggested changes, Scott Weingart (@scottbot) contacted me about using this lesson with students who may have Windows computers. The additional steps seem pretty concise, so I will be adding those Windows steps in (documented in this annotation). Scott said he'd look the steps over and possibly assign the lesson to his students to try/give feedback on Thursday 3/24, so we may have some more review ideas that way.

[amandavisconti]

@fredgibbs I'm working through your excellent suggestions; could you clarify the following? "There could even be a bit more on selling the virtues of having a static personal website (even when without much technical skill) rather than rely on generic templates and platforms, and be able to fully share and manage your own content easily over time. I know you get into this a bit later, too, but that could be a big selling point." Do you mean in the opening paragraph? Are there specific things I didn't cover below (in the newly expanded/updated section on why a Jekyll-generated static site) I should add, or do you just mean a summary/sneak peak of what those things are?

[fredgibbs]

@amandavisconti I think you've already done a lot to clarify that point. The only thing you might add, in the very first point of the lesson (this lesson is for you, if...) that static sites allow full control (as simple as complex as you'd like) in addition to maintenance, preservation, etc. And then you have the fuller explanation later.

One bit that I just noticed: the 2nd paragraph of static vs dynamic websites seems like it should, following the scheme set up by the 1st paragraph, introduce static sites in general before introducing jekyll. (Like it should start with "static sites are ...." You have a great explanation of dynamic sites; I'd love the parallel for static sites. You might even mention (if you think it helps) that static sites could of course be hand-written HTML. And THEN, after defining static sites in general, move into your already excellent introduction of jekyll (a particular way of creating them).

All of your edits that I've noticed so far are fantastic!

[amandavisconti]

@fredgibbs I've now gone through all your review comments and addressed these in a series of commits. Thanks again—these have helped me make the lesson much stronger!

[paigecm]

Okay! First off, on the whole, this tutorial worked exactly as promised, and was easy, if slightly time-consuming, to go through. Thanks for putting it together!

Audience It seems to me that this tutorial could be really helpful for an audience with intermediate knowledge and command line familiarity, OR an audience without much command line and/or git familiarity at all. I'm in the former group and I breezed through it, once I got Xcode sorted, and I found it wonderfully straightforward and helpful. For the latter group, I think that in almost every case, you provide a good level of explanation that will allow them to actually do some powerful stuff without a lot of advance preparation. There are a couple of other places where I think that less-experienced users might get hung up; I'll note those below.

The main areas where I think some key improvements could be made are Payoff and Getting Ready.

Contextualizing the purpose of the tutorial, i.e. Payoff I know you've already responded to feedback to make it clearer what a static site is, as opposed to a dynamic site. I think that's helpful, but I would go even a little further, and explain to people that a Jekyll/Github site would work well for a blog or a basic homepage with contact info and/or a CV, but would not work as well as a media-rich site with embedded HTML, etc. I tried to sort out whether there was a simple way to include pictures or files via Jekyll (as opposed to linking to a public file in Google Drive or DropBox), but without success (note: I only tried to do it locally, rather than through github). But images and files seem like the sorts of things that people might want to include (in fact, it seems more likely to me that they would want that than that they would want this for blogging, based on my experiences working with grad students new-to-DH in the last 3-4 years). If there's a tutorial that you can link to, I think that would be sufficient.

Getting Xcode up and running (Getting ready) I was running Xcode on a work machine a year or so ago, so I'm somewhat familiar with it, and was not surprised when the App Store version couldn't be installed because I'm only running OS 10.10.5, rather than 10.11. I suspect that some of your Mac users will be in the same situation, so it would be useful to let them know that they can download a previous version here:

https://developer.apple.com/downloads/

I used the Version comparison table at Wikipedia (https://en.wikipedia.org/wiki/Xcode#Xcode_7.0_-_7.x_.28since_Swift_2.0_support.29) to determine what version would work for me (I'm running 10.10.5, the last version before El Capitan) -- and 7.2.1 did the trick. I had to identify as a developer in order to access the versions, but that was a tiny and quick step.

Once Xcode had downloaded and installed, I ran into trouble opening it because it got stuck at the tail end of the Verifying Application step. I gave it several hours, twice, and then went looking for other people with the same problem, and found this exchange at StackOverflow, which did indeed solve the problem. I can't think of another case where I'd disable the Gatekeeper, but I was happy to do it strictly for Xcode.

Is the full version of Xcode needed? That brings me to another question, though: is the whole Xcode program actually necessary? It's certainly not required to install homebrew (I've had that on my machine for a while now; all you need for it are the Apple Command Line Tools). I was bemused to find that having installed Xcode, I never opened it -- until I accidentally double-clicked on one of the Markdown files in the _posts folder, and discovered that it opened in Xcode by default, and that Xcode actually includes a Markdown editor. I prefer TextWrangler, because it can do more than edit Markdown, but maybe for some people, using the built-in Xcode editor would simplify things, and require them to download one less piece of software. Or, alternately, I recommend having people skip the Xcode install and just get the Command Line Tools, and then get the text editor they prefer.

Skimmability I think this is a challenging lesson to make skimmable, especially for less experienced audiences, but the screenshots are excellent.

Workflow I wouldn't divide this into smaller lessons -- I think you've done a great job at separating the lesson into discrete steps and providing explanations without opening up rabbit holes for people to fall into (while still giving them plenty of links to relevant content if they want to follow up). It looks like you have a recommendation above to explain how you can set up your own machine as a local webserver -- I would have found that interesting but ultimately distracting from the tutorial's primary momentum, so if you do end up covering that, I would make it a separate lesson/thing.

Integrating with the Programming Historian A++ throughout -- I didn't need the links, but felt more secure because they were there, and especially appreciated the links at the end for further developments with Jekyll.

I've covered the Xcode hangups above -- the one other area where I anticipate people running into trouble is in the section on Hosting on Github Pages, in Step 1 ("Click on the Choose button..."). At first, this didn't work for me because my Library folder was still hidden (I've always accessed it through Finder-->Go and holding down the Option key -- but that doesn't work for selecting a file in the GitHub Desktop menu). I used the instructions here to fix that. Maybe this is a problem that other people won't run into, so doesn't need to be addressed -- but it seems like it would be a shame for them to get almost to the end, and then get stuck.

Okay -- I think that's it! If anything here is unclear, feel free to ask, and I'll be happy to clarify. Thanks again for letting me kick the tires!

[amandavisconti]

@paigecm Thanks so much for testing the lesson and your thorough and really helpful comments! I may have a few more questions as I work through these, but one quick question: do you have a rough sense of the amount of time the lesson took? (This will help me give others a general sense of the time to set aside.)

Thanks again, Paige!

[amandavisconti]

Looks like I should verify whether Xcode and/or NodeJS are actually required for this lesson (official Jekyll docs say to install them, but Paige notes Xcode not clearly being used, and I think NodeJS might have been required for Jekyll 2.0 but not the current 3.0). I'll uninstall and test when I go through Paige's suggestions.

[amandavisconti]

@fredgibbs I'm curious about the current PH theme: I definitely understand wanting all lessons to share the same theming, but I notice my lesson is a bit harder to visually skim online than it is in Typora—and I think I'm missing 1) code being set off in a gray box instead of one a white background (easier to see, easier to say "copy and paste everything in the box even if the line looks like it ends"), and 2) have a line/border-bottom set under headings really helped with visual chunking when jumping around the page or scrolling down to see how much there was to do. Would this be something worth my mocking up just on this under-review lesson for you/other editors to look at?

[paigecm]

I'm really sorry I didn't catch the reason for Xcode on my first readthrough, or I'd have said something then: I was so intent on getting it up and running that I didn't catch on to exactly what it was for.

Once I got past the Xcode bit and into the installing part, it took me just under 2.5 hours ... though that's without Homebrew, since I already had it on my system.

[paigecm]

(and that time is with occasional stops and starts as I worked on other things/noodled around on the net while waiting for Terminal processes to complete.)

[wcaleb]

@amandavisconti Thanks for pointing out the styling issues. We've wanted to refresh the visual look for a while now, but haven't been able to do it in all the move-to-GitHub commotion. If you want to mock up something for this lesson, I think we'd be happy to take a look!

[wcaleb]

@amandavisconti Regarding copying and pasting from code blocks, we also toyed with a "select all" button for code:

https://github.com/programminghistorian/jekyll/issues/23

If you think that's worth implementing, would appreciate the feedback.

[fredgibbs]

I was just about to write exactly what @wcaleb did. I don't think we'd want to have your lesson be stylistically different than the others, but I would be happy to implement such changes across the lessons. The current design has served us well, but needs a significant refresh. If you have ideas for your own lesson, we would love to see them!

[amandavisconti]

@fredgibbs @wcaleb Just added a comment to the paste-button issue, and I added the following CSS to style.css using Firebug to enact the ideas I mentioned:

h2 { border-bottom: 1px solid #555555; }

h3 { text-align: left; }

code { background: #ededed; border: 2px solid #f6f6f6; padding: 10px; color: #000; }

[amandavisconti]

@fredgibbs Another person, Jamie Howe, successfully completed my lesson and shared some comments on the Jekyll site he created. I quote them here for reference:

Well, if you’re viewing this on the web, then my following of this tutorial has been a success. I chose this particular tutorial (and was particularly excited for it) because there were explicit instructions for Windows users, a group of which I am contentedly a part. Wherever else I have found mentions of Windows and Jekyll in the same breath, it sums up to: Jekyll does not work on Windows, full stop. Jekyll works on Windows, but you need a full grasp of arcaninma to make it so. I found neither to be true, and in fact was probably easier and quicker than the instructions gave for the Mac (no 4-hour Xcode downloads for me). However as a disclaimer: I had both Ruby and chocolatey already installed, albeit separately. I think it’s a good idea to let chocolatey handle the installation of Ruby for new users but for me Ruby actually came first. From there, nearly everything was explained in a straight-forward and friendly manner. I ran into a bit of trouble with one of the bundler dependencies because MalwareBytes did NOT like one of its required files, but a temporary disable solved that issue. I appreciated being shown how to run the server locally because this was not something I had previously known how to do in any capacity, although I knew it was somehow possible. Seeing it in action was very helpful. I would have liked a little bit more of a primer on Markdown, but I understand that is technically outside the scope of the tutorial. I ran into the biggest problem during the section on hosting on Github Pages. Whereas up until this point there wasn’t a huge challenge in extrapolating from the Mac screenshots, the introduction of native apps for Windows 10 has changed the UI. GitHub Desktop for Windows is a pleasant experience to use but the functionality does not match the instructions. I was able to figure it out with a bit of trial and error but wound up creating a repo somewhere on my computer and then maybe deleting it? The biggest changes were: “Create & Add Repository” is just “Create Repository”, while “Add Repository” is a separate function designed to add an existing local repo. It seemed necessary to “Commit to Master” once before continuing and adding a branch. I don’t think this is strictly true, and I don’t think this did anything bad, just mirrored the master to GitHub? Maybe? While neither is particularly huge, they threw me a bit until I was able to accomplish the instructions by playing around. Regardless, it seems successful (and way quicker than editing html by hand every time I update something). More importantly I feel like this is easy enough to do on my own in the future and play around, which is a good feeling with which to come out of a tutorial.

[nabsiddiqui]

If this is still something in need of review, I will be also happy to add my comments. I am switching my personal website to jekyll soon, and I have to go through these steps either way.

[amandavisconti]

I just committed a lesson update with all the improvements suggested by @paigecm and Jamie Howe's reviews. In particular, removed the ponderous full Xcode install (thanks for noticing only the command-line tools were needed, @paigecm!), and we've now had the lesson reviewed successfully by both Mac and a Windows user.

[fredgibbs]

Thanks @paigecm for your very helpful comments!

@nabsiddiqui, thanks for volunteering! Because we've already had two outside reviews (and revisions), we are about to publish the lesson on the main site within the next week and close the formal review process. However, if you end up using the lesson and want to write up a few notes about your experience and post them as an issue on the main site, that would be very helpful!

[nabsiddiqui]

If you have already submitted it, then I will just wait until another review is needed. Looks like a great tutorial though. I'll be following it myself when I switch to jekyll for my personal website sometime over the summer.

[fredgibbs]

This lesson has completed the review process and is now published on the gh-pages branch. Thanks to everyone who has provided feedback along they way!